geolens-mcp
Apache-2.0 read-only Model Context Protocol server for GeoLens.
Point a coding agent (Claude Code, Cursor, Codex, …) at a GeoLens instance so it can discover datasets, inspect schemas, read features and maps, and run read-only SQL from inside a dev session.
Read-only by design. No writes, ingest, or admin. The discovery tools are GETs against existing API endpoints; query is a POST mechanically but executes inside the server's READ ONLY SQL sandbox, so it cannot modify anything. Calls are scoped to the caller's access: with an API key, the agent sees the datasets that key's user can see; with no credential it sees only public/published data (query additionally requires a credential whose user holds the AI-chat permission — read_only API keys work, via a route-specific server-side carve-out).
Install
The server reads its target instance and credentials from the environment (same names as the geolens CLI):
| Variable | Required | Meaning |
|---|
GEOLENS_INSTANCE | yes | Instance URL, e.g. https://geolens.example.com. The /api suffix is appended automatically if you omit it. |
GEOLENS_API_KEY | recommended | API key, sent as X-Api-Key. Create one in Settings → API keys. Omit for public-only access. |
GEOLENS_TOKEN | — | JWT bearer token, used only if GEOLENS_API_KEY is unset. |
Register with an MCP client
Claude Code:
claude mcp add geolens -e GEOLENS_INSTANCE=https://geolens.example.com -e GEOLENS_API_KEY=... -- uvx geolens-mcp
Cursor / Codex / any client that reads an mcpServers block:
{
"mcpServers": {
"geolens": {
"command": "uvx",
"args": ["geolens-mcp"],
"env": {
"GEOLENS_INSTANCE": "https://geolens.example.com",
"GEOLENS_API_KEY": "your-api-key"
}
}
}
}
| Tool | What it does |
|---|
search_datasets | Catalog search by free text (semantic ranking where the instance enables it). Returns dataset records as GeoJSON features with safe origin and freshness state; health/check/refresh keys are null when unavailable in the search summary. |
get_dataset_schema | A dataset's columns, geometry type, CRS/SRID, feature count, extent, and source trust metadata. |
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 | One saved map's full metadata, including layers and view state. |
query | One read-only SQL SELECT through the server's hardened sandbox (#565): single statement over data.* tables, allowlisted functions, a mandatory restrict_tables scope, and a strict server-side budget (statement timeout, self-join cap, row limit, rate limits). Needs a credential whose user has the AI-chat permission; requires GeoLens ≥ the release that ships POST /api/query/. |
Develop
cd mcp
uv run --extra dev python -m pytest -v