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

Metadata

Release files for geolens-mcp 1.21.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geolens-mcp 1.21.1
File	Size	Uploaded
geolens_mcp-1.21.1.tar.gz	69.7 kB	Oct 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for geolens-mcp 1.21.1
File	Interpreter	ABI	Platform	Reset
geolens_mcp-1.21.1-py3-none-any.whl 15.2 kB Oct 2, 2026	Python 3	none	any	Details

Total release size: 84.9 kB

Release files / geolens_mcp-1.21.1.tar.gz

Download URL	geolens_mcp-1.21.1.tar.gz
Size	69.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`5627c61d4a23db1beaa9e23d4e4bd97c6b3ad9122504b37f85c5c56e7cfa247f`
BLAKE2b-256 checksum How to use checksums	`53265d2d2493de7196d48677fb2e3e836fe4722db7dd450d4d16c90e556279e1`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / geolens_mcp-1.21.1-py3-none-any.whl

Download URL	geolens_mcp-1.21.1-py3-none-any.whl
Size	15.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`77cbc76e5146183b4c5b65db6183302ee5ad76f301553b54e1ce5d003b337f53`
BLAKE2b-256 checksum How to use checksums	`95ed771059d6788cd8f951723fb464e4e57ff2e9bec1023a9a0a7c101bfd8fd8`
Upload date	Oct 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`