geolens-mcp

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

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

Configure

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"
      }
    }
  }
}

Tools

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