MCP Server
Ce contenu n’est pas encore disponible dans votre langue.
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.
Install
Section titled “Install”pip install geolens-mcp # or: uvx geolens-mcpgeolens-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.
Configure
Section titled “Configure”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.
| Variable | Required | Meaning |
|---|---|---|
GEOLENS_INSTANCE | Yes | Instance 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_KEY | Recommended | API 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. |
Register with an MCP client
Section titled “Register with an MCP client”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:
claude mcp add geolens \ -e GEOLENS_INSTANCE=https://geolens.example.com \ -e GEOLENS_API_KEY=... \ -- uvx geolens-mcpThat 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.
Merge the mcpServers block into claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and
restart Claude Desktop.
If Desktop reports spawn uvx ENOENT, it launched the server with a minimal
PATH. Replace "uvx" in command with the absolute path from which uvx
(where uvx on Windows).
Save the mcpServers block as .cursor/mcp.json in your project, or
~/.cursor/mcp.json to apply everywhere, and restart Cursor.
Codex reads TOML. Add a [mcp_servers.geolens] table to
~/.codex/config.toml:
[mcp_servers.geolens]command = "uvx"args = ["geolens-mcp"]
[mcp_servers.geolens.env]GEOLENS_INSTANCE = "https://geolens.example.com"GEOLENS_API_KEY = "your-api-key"Or register it from the command line:
codex mcp add geolens \ --env GEOLENS_INSTANCE=https://geolens.example.com \ --env GEOLENS_API_KEY=... \ -- uvx geolens-mcpAny client that speaks stdio MCP accepts the plain {command, args, env}
shape of the mcpServers block above; check its docs for the file it reads.
| Tool | What it does |
|---|---|
search_datasets | Catalog 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_schema | A dataset’s columns, geometry type, CRS/SRID, feature count, and extent, plus the source-trust fields origin, source_health, and source_freshness. |
get_features | Bounded GeoJSON features for a dataset (OGC API — Features), with optional bbox. |
list_maps | Saved maps (id, name, visibility, layer count). |
get_map | A 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_stories | Published 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_story | One 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. |
aggregate | An 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. |
query | One 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.
Using aggregate
Section titled “Using aggregate”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.
op | Body |
|---|---|
count | Nothing else. |
stats | column and stats, a list of count, sum, avg, min or max. |
value_counts | column and limit (1 to 50, default 10). |
histogram | column and bins (1 to 50, default 10). |
group_by | group_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). |
rows | columns (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): thebboxholds over 500,000 rows. Narrow it or drop it.invalid_column,invalid_cursor,invalid_filter,no_geometry,query_timeout,query_data_errorandresult_too_large(422): fix the request.query_busyorquery_at_capacity(429): retry after 200 to 400 ms with jitter.query_unavailable(503): retry after theRetry-Afterdelay.
Use query for anything aggregate can’t express.
Using query
Section titled “Using query”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.
Map authoring
Section titled “Map authoring”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.
| Tool | What it does |
|---|---|
create_map | Creates a private map with an optional description and basemap. Returns its id and app URL. |
add_layer | Adds a dataset as a layer, with an optional style and popup fields. |
update_layer_style | Restyles a layer or changes its popup fields. |
set_camera | Sets the view the map opens at. |
set_basemap | Sets 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)See also
Section titled “See also”- Client SDKs: the Python SDK that
geolens-mcpbuilds on, and the CLI-vs-SDK-vs-MCP-vs-API decision table - CLI & Manifests: the shared
GEOLENS_INSTANCEandGEOLENS_TOKENenvironment variables, for terminal and CI ingestion - API Authentication: JWT and API-key details for the credentials above
- Search & Discovery: what
search_datasetsreturns, including semantic ranking - Examples: MCP prompts: prompts to try against the public demo, each naming the tools it drives