Ir al contenido
getgeolens.com

MCP Server

Esta página aún no está disponible en tu idioma.

The GeoLens MCP server (geolens-mcp) is a Model Context Protocol server. Point a coding agent (Claude Code, Cursor, Codex, and any other MCP client) at a GeoLens instance and it can discover datasets, inspect schemas, and read features and maps from inside a dev session. With a map_author API key it can also create and style maps (Map authoring). It is Apache-2.0 licensed and built on the Python SDK, so every tool maps to a real endpoint in the API reference.

Terminal window
pip install geolens-mcp # or: uvx geolens-mcp

geolens-mcp needs Python 3.11 or newer, one minor version above the Python SDK it builds on, which supports 3.10.

uvx runs the server without a persistent install, which is what the client-registration examples below use.

geolens-mcp is released alongside GeoLens itself, so run the version that matches your instance: GET /api/health reports it. The examples repo publishes the pinned command and explains the trade-off of pinning.

The server reads its target instance and credentials from the environment — the same GEOLENS_INSTANCE and GEOLENS_TOKEN names the CLI uses. GEOLENS_API_KEY is read by the MCP server only; the CLI takes a key through geolens login --api-key.

VariableRequiredMeaning
GEOLENS_INSTANCEYesInstance URL, e.g. https://geolens.example.com. The /api suffix is appended automatically if you omit it, and left alone if you include it. The SDKs do not append it, so if one exported value feeds the SDK too, include /api.
GEOLENS_API_KEYRecommendedAPI key, sent as X-Api-Key. Omit for public-only access. See Authentication → API keys for how to obtain one.
GEOLENS_TOKEN—JWT bearer token, used only if GEOLENS_API_KEY is unset.

Every client needs the same inputs: the command uvx geolens-mcp and the GEOLENS_* variables above in the server’s environment. Most clients read them from an mcpServers block:

{
"mcpServers": {
"geolens": {
"command": "uvx",
"args": ["geolens-mcp"],
"env": {
"GEOLENS_INSTANCE": "https://geolens.example.com",
"GEOLENS_API_KEY": "your-api-key"
}
}
}
}

Where that block goes differs per client, and Codex reads TOML instead. Ready-to-paste files for each client, pointed at the public demo, live in the examples repo under mcp/clients/.

One command registers the server:

Terminal window
claude mcp add geolens \
-e GEOLENS_INSTANCE=https://geolens.example.com \
-e GEOLENS_API_KEY=... \
-- uvx geolens-mcp

That writes to the local scope (this project, this machine). Add -s user to make the server available in every project. For a config that travels with the repository, put the mcpServers block above in a .mcp.json at the project root and commit it. Keep the real key out of that file: reference a variable your shell already exports instead ("GEOLENS_API_KEY": "${GEOLENS_API_KEY}"), or register locally with claude mcp add.

ToolWhat it does
search_datasetsCatalog search by free text (semantic ranking where the instance enables it). Returns a compact object with type, numberMatched, numberReturned and features. Each hit has id, bbox and the properties title, description (cut at 300 characters), record_type, geometry_type, feature_count, crs, keywords and updated, plus source_origin, source_freshness, source_health, source_health_detail, last_checked_at and last_refreshed_at. There is no geometry and there are no links. Search makes no per-result detail request, so the last four are null when the catalog summary has no value; call get_dataset_schema for those.
get_dataset_schemaA dataset’s columns, geometry type, CRS/SRID, feature count, and extent, plus the source-trust fields origin, source_health, and source_freshness.
get_featuresBounded GeoJSON features for a dataset (OGC API — Features), with optional bbox.
list_mapsSaved maps (id, name, visibility, layer count).
get_mapA summary of one saved map: id, name, description, visibility, center_lng, center_lat, zoom, bearing, pitch, basemap_style, show_basemap_labels, terrain_config, layer_count and updated_at. Each layer has id, dataset_id, dataset_name, dataset_table_name, dataset_geometry_type, display_name, visible, layer_type and filter. dashboard_widget_count is the number of dashboard widgets. Styling, popups, labels, column info and sample values are not included.
list_storiesPublished stories you can read: id, title, summary, visibility and chapter count. Drafts are never listed. Takes search (title or summary), limit (1 to 200, default 50) and offset.
get_storyOne story’s published version: title, summary, visibility and the document with its chapters. Each chapter has a title, blocks and a scene (map_id, camera, layer_visibility). A chapter on a map you can’t read comes back without its scene and with scene_hidden true. document is null until the story is published, and a story you can’t read answers 404. It never returns the draft.
aggregateAn exact aggregate over a dataset’s rows, without SQL. Takes a dataset id and a request body chosen by op: count, stats, value_counts, histogram, group_by or rows. See Using aggregate.
queryOne read-only SQL SELECT over data.* tables, through the server’s hardened sandbox. Returns {columns, rows, row_count, truncated}.

search_datasets, get_features, list_maps and list_stories take a limit of 1 to 200 (default 10, 10, 50 and 50) and page with offset; list_maps and list_stories also take a search text filter. Every tool returns compact JSON text. The get_features bbox is minx,miny,maxx,maxy in WGS84 regardless of the dataset’s own SRID. Raster datasets have no features, so get_features against one errors rather than returning an empty collection; check record_type in get_dataset_schema first. A dataset or map id that is not a UUID is rejected by geolens-mcp itself (Invalid id (expected a UUID)) before any request reaches the instance, which is a different error from a 404.

aggregate POSTs to the dataset’s aggregate route but only reads. Every op takes an optional CQL2-JSON filter and an optional bbox as [west, south, east, north] in WGS 84. Unknown keys are refused.

opBody
countNothing else.
statscolumn and stats, a list of count, sum, avg, min or max.
value_countscolumn and limit (1 to 50, default 10).
histogramcolumn and bins (1 to 50, default 10).
group_bygroup_column with stat and column, or stats as a list of {stat, column}. Optional date_bucket (day, week, month or year), sort_by, sort and limit (1 to 50).
rowscolumns (up to 20), sort_column, sort, limit (1 to 100, default 25) and cursor. It lists features a page at a time, each with its gid and bbox and no geometry. Pass the previous page’s next_cursor as cursor, under the same sort.

The answer is {op, result, approximate, cached}. The dataset needs a feature table, so a raster is refused, and a dataset you can’t read answers 404. The route allows 10 requests a second. Refusals keep the route’s status and carry a code:

  • too_wide (422): the bbox holds over 500,000 rows. Narrow it or drop it.
  • invalid_column, invalid_cursor, invalid_filter, no_geometry, query_timeout, query_data_error and result_too_large (422): fix the request.
  • query_busy or query_at_capacity (429): retry after 200 to 400 ms with jitter.
  • query_unavailable (503): retry after the Retry-After delay.

Use query for anything aggregate can’t express.

query is the one tool that is not a GET; it POSTs to the sandbox endpoint and is still strictly read-only. A single SELECT is allowed, over an allowlisted function set (aggregates, math, string, date, JSON, and common PostGIS such as ST_Area, ST_DWithin, ST_Intersects, ST_IsValid, ST_GeometryType, ST_NPoints, ST_AsText, ST_MakeEnvelope, ST_GeomFromText and ST_GeomFromGeoJSON, plus geography(), geometry() and the && operator), under a server-side budget: a few seconds of runtime, a repetition cap on self-joins, a row_limit between 1 and 1000 (default 100), at most 25 entries in restrict_tables, 20,000 characters of SQL, 100 output columns, an 8 MB response, and 30 queries a minute per user (60 per IP). The sandbox rejects writes, other schemas, and unlisted functions with a short reason; a refused function is named in it, unless its name is quoted. Geometry columns come back as hex EWKB, so select ST_AsText(geom) or ST_AsGeoJSON(geom) to read a geometry. ST_AsGeoJSON(geom, 6) rounds coordinates to six decimals, which suits display but can make a small polygon invalid.

This endpoint is tighter than AI chat on one axis: output-amplifying functions the shared allowlist otherwise admits are dropped here — concat, concat_ws, format, replace, regexp_replace, array_to_string, json_build_object, and jsonb_build_object — and with concat blocked the || concatenation operator is refused too. Assemble strings on the client instead.

It takes restrict_tables as a required, non-empty list. Every table the query touches must be listed there, and the scope can only narrow what the credential already sees. The usual workflow is search_datasets to find a dataset, then get_dataset_schema for its table_name and columns, then reference it as data.<table_name> in the SQL and list that same table_name in restrict_tables.

query requires credentials whose user has the AI-chat permission, so anonymous configurations cannot use it: without one it returns 401 Could not validate credentials. A read_only API key works, because the route is exempt from the read-only key restriction. The other eight tools work without a credential against public/published data.

Requires GeoLens 1.32 or newer.

With a map_author API key in GEOLENS_API_KEY, the server can also build a map. Create the key in Settings > API Keys with the Map author scope. The key reads what a read-only key reads. It can change only the private maps it created: it cannot edit a map made in the app or by another key, delete anything, rename a map or layer, or share a map or change its visibility.

The authoring tools refuse to run with any other credential, including a full key, a publish key or GEOLENS_TOKEN. They say so before sending a request. The read tools keep working with those credentials.

ToolWhat it does
create_mapCreates a private map with an optional description and basemap. Returns its id and app URL.
add_layerAdds a dataset as a layer, with an optional style and popup fields.
update_layer_styleRestyles a layer or changes its popup fields.
set_cameraSets the view the map opens at.
set_basemapSets the map’s basemap.

A style takes one of three forms:

  • A single colour.
  • A colour per value of a text, boolean or integer column, up to 100 values.
  • A colour per class of a numeric column, by equal interval, quantile, natural breaks or standard deviation, or by breaks you list yourself.

Colours are a named ramp or a list of hex colours, one per value or class. popup_fields lists the columns a feature popup shows. The map builder opens the layer with the same settings.

Each new layer is drawn beneath the layers already on the map, and the key cannot reorder them, so add the layer you want on top first.

create_map(name="Street trees", basemap="blank")
add_layer(map_id="<id>", dataset_id="<id>", style={"type": "categories", "column": "species"}, popup_fields=["species", "planted"])
update_layer_style(map_id="<id>", layer_id="<id>", style={"type": "classes", "column": "dbh", "method": "quantile", "colors": "Greens"})
set_camera(map_id="<id>", center=[-73.97, 40.78], zoom=13)
  • Client SDKs: the Python SDK that geolens-mcp builds on, and the CLI-vs-SDK-vs-MCP-vs-API decision table
  • CLI & Manifests: the shared GEOLENS_INSTANCE and GEOLENS_TOKEN environment variables, for terminal and CI ingestion
  • API Authentication: JWT and API-key details for the credentials above
  • Search & Discovery: what search_datasets returns, including semantic ranking
  • Examples: MCP prompts: prompts to try against the public demo, each naming the tools it drives