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, and read features and maps from inside a dev session.

Read-only by design. Every tool is a GET against an existing API endpoint — no writes, ingest, or admin. 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.

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.

Not yet included

A query tool (run SQL through GeoLens's read-only sandbox) is intentionally not in this release. The sandbox has no direct REST endpoint today, and exposing raw SQL over HTTP needs security hardening (cost/DoS bounds, rate limiting, mandatory dataset scope) before it's safe to point at a production instance. Tracked in #565.

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.11.1.tar.gz (66.2 kB view details)

Uploaded Aug 11, 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.11.1-py3-none-any.whl (13.8 kB view details)

Uploaded Aug 11, 2026 Python 3

File details

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

File metadata

Download URL: geolens_mcp-1.11.1.tar.gz
Upload date: Aug 11, 2026
Size: 66.2 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.11.1.tar.gz
Algorithm	Hash digest
SHA256	`6963e6f614c8d3401e68575c44cc1103b6eee32d9d7d2f0a5e17eaf3b9016b7d`
MD5	`fef342d982ed9df9aea45bcb20a313d1`
BLAKE2b-256	`259a64ee4ff547065598a0687320cf800b044f3d0191ead7657480b761163144`

See more details on using hashes here.

File details

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

File metadata

Download URL: geolens_mcp-1.11.1-py3-none-any.whl
Upload date: Aug 11, 2026
Size: 13.8 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.11.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`7d853eeeaada0cde2f52950e41e1b0981e281cd4168b17b82847231b60d74ff0`
MD5	`2f1905c4a27747cac31fa29667e6e170`
BLAKE2b-256	`eed5e850e6adc530ae8430b6542b871a289be70035e3c342efd2865b26eeef09`