MCP Server

Ce contenu n’est pas encore disponible dans votre langue.

The GeoLens MCP server (geolens-mcp) is a read-only Model Context Protocol server. Point a coding agent (Claude Code, Cursor, Codex, and any other MCP client) at a GeoLens instance and it can discover datasets, inspect schemas, and read features and maps from inside a dev session. It is Apache-2.0 licensed and built on the Python SDK, so every tool maps to a real endpoint in the API reference.

Install

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

uvx runs the server without a persistent install, which is what the client-registration examples below use.

Configure

The server reads its target instance and credentials from the environment — the same variable names the CLI uses:

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`. Omit for public-only access. See Authentication → API keys for how to obtain one.
`GEOLENS_TOKEN`	—	JWT bearer token, used only if `GEOLENS_API_KEY` is unset.

Register with an MCP client

Claude Code — one command registers the server for the current project:

claude mcp add geolens \
  -e GEOLENS_INSTANCE=https://geolens.example.com \
  -e GEOLENS_API_KEY=... \
  -- uvx geolens-mcp

Cursor, Codex, or 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.
`get_dataset_schema`	A dataset’s columns, geometry type, CRS/SRID, feature count, and extent.
`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` over `data.*` tables, through the server’s hardened sandbox. Returns `{columns, rows, row_count, truncated}`.

Using `query`

query is the one tool that is not a GET; it POSTs to the sandbox endpoint and is still strictly read-only. A single SELECT is allowed, over an allowlisted function set (aggregates, math, string, date, JSON, and common PostGIS such as ST_Area, ST_DWithin, ST_Intersects), under a server-side budget: a few seconds of runtime, a repetition cap on self-joins, and a row_limit between 1 and 1000 (default 100). The sandbox rejects writes, other schemas, and unlisted functions with a short reason.

It takes restrict_tables as a required, non-empty list. Every table the query touches must be listed there, and the scope can only narrow what the credential already sees. The usual workflow is search_datasets to find a dataset, then get_dataset_schema for its table_name and columns, then reference it as data.<table_name> in the SQL and list that same table_name in restrict_tables.

query requires credentials with AI-chat permission, so anonymous configurations cannot use it. The other five tools work without a credential against public/published data.