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

Release files for geolens-mcp 1.18.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.18.1
File	Size	Uploaded
geolens_mcp-1.18.1.tar.gz	69.5 kB	Sep 5, 2026	Details

Built distribution (wheel)

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

Total release size:84.7 kB

Release files / geolens_mcp-1.18.1.tar.gz

Download URL	geolens_mcp-1.18.1.tar.gz
Size	69.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`cf42d85e56a5a66182ab015a9568cb7844873b212d237e11d87c73c8eaa8b1e9`
BLAKE2b-256 checksum How to use checksums	`ed29b00094345e28f5573c15613bc55f3b463070d40ed5d16d760fc53a278309`
Upload date	Sep 5, 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.18.1-py3-none-any.whl

Download URL	geolens_mcp-1.18.1-py3-none-any.whl
Size	15.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`fa64025a03305a1d18bd8ece33b61392ec7b564385f76d4512ab191bcee67f73`
BLAKE2b-256 checksum How to use checksums	`209acb5016dc9b0872b87d2ca4e70062f76a22c6766e195eebbbe9106a30c601`
Upload date	Sep 5, 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}`