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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

geolens_mcp-1.16.0.tar.gz (69.4 kB view details)

Uploaded Aug 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

geolens_mcp-1.16.0-py3-none-any.whl (15.2 kB view details)

Uploaded Aug 27, 2026 Python 3

File details

Details for the file geolens_mcp-1.16.0.tar.gz.

File metadata

Download URL: geolens_mcp-1.16.0.tar.gz
Upload date: Aug 27, 2026
Size: 69.4 kB
Tags: Source
Uploaded using 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}

File hashes

Hashes for geolens_mcp-1.16.0.tar.gz
Algorithm	Hash digest
SHA256	`d756832f8bd8542c855dfee40255e2e24441dc47ec46b2e63436df7032ecdbae`
MD5	`acb9c2cc0686545d47a09a177be726d8`
BLAKE2b-256	`94d5952e2c27939c8fd921600446f469e47df0e43bca8c36fa2c16c7d9a1a464`

See more details on using hashes here.

File details

Details for the file geolens_mcp-1.16.0-py3-none-any.whl.

File metadata

Download URL: geolens_mcp-1.16.0-py3-none-any.whl
Upload date: Aug 27, 2026
Size: 15.2 kB
Tags: Python 3
Uploaded using 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}

File hashes

Hashes for geolens_mcp-1.16.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`7dee14c8b89b4b8b4eeb918fa4409148a2b439350781b61d2b7aa64933f09a4e`
MD5	`2fbd51265b679c5434fe3492b7ff2800`
BLAKE2b-256	`f12b2ad1f70b1439c1df377677e8b3197db403f4b864fb551b82301b2c69fb78`