Skip to content
MCP server

GeoLens

Read-only agent access to a self-hosted GeoLens spatial catalog, maps and SQL

Runs locallyStatus and history
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
1.32.0
Listing updated
3 days ago

About GeoLens

GeoLens is an open-source MCP server for databases. It runs locally on your machine and is started by your AI client.

GeoLens is an Apache 2.0, self-hosted geospatial catalog and web map builder, and this server points a coding agent at one instance so it can work with spatial data from inside a dev session. It has no write, ingest or admin tools, and every call is scoped to the caller's access.

The agent can search datasets, read a dataset's schema, page through features, and list or fetch saved maps and their layers. It can also list published stories and their chapters; drafts are never read. aggregate returns exact counts, statistics, histograms and group-bys over one dataset, and query runs a single sandboxed SELECT. The README steers counts and summaries towards aggregate.

Two refusal cases are documented: too_wide means the bounding box holds over 500,000 rows and should be narrowed, and query_busy means two aggregates are already running. Configuration uses GEOLENS_INSTANCE, plus GEOLENS_API_KEY for non-public data. It installs from PyPI as geolens-mcp.

Install

Run in a terminal

claude mcp add geolens --env GEOLENS_INSTANCE='<GEOLENS_INSTANCE>' --env GEOLENS_API_KEY='<GEOLENS_API_KEY>' --env GEOLENS_TOKEN='<GEOLENS_TOKEN>' -- uvx geolens-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "geolens": {
      "command": "uvx",
      "args": [
        "geolens-mcp"
      ],
      "env": {
        "GEOLENS_INSTANCE": "<GEOLENS_INSTANCE>",
        "GEOLENS_API_KEY": "<GEOLENS_API_KEY>",
        "GEOLENS_TOKEN": "<GEOLENS_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "geolens": {
      "command": "uvx",
      "args": [
        "geolens-mcp"
      ],
      "env": {
        "GEOLENS_INSTANCE": "<GEOLENS_INSTANCE>",
        "GEOLENS_API_KEY": "<GEOLENS_API_KEY>",
        "GEOLENS_TOKEN": "<GEOLENS_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "geolens": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "geolens-mcp"
      ],
      "env": {
        "GEOLENS_INSTANCE": "<GEOLENS_INSTANCE>",
        "GEOLENS_API_KEY": "<GEOLENS_API_KEY>",
        "GEOLENS_TOKEN": "<GEOLENS_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "geolens": {
      "command": "uvx",
      "args": [
        "geolens-mcp"
      ],
      "env": {
        "GEOLENS_INSTANCE": "<GEOLENS_INSTANCE>",
        "GEOLENS_API_KEY": "<GEOLENS_API_KEY>",
        "GEOLENS_TOKEN": "<GEOLENS_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "geolens": {
      "command": "uvx",
      "args": [
        "geolens-mcp"
      ],
      "env": {
        "GEOLENS_INSTANCE": "<GEOLENS_INSTANCE>",
        "GEOLENS_API_KEY": "<GEOLENS_API_KEY>",
        "GEOLENS_TOKEN": "<GEOLENS_TOKEN>"
      }
    }
  }
}

Configuration

  • GEOLENS_INSTANCEBase URL of the GeoLens instance, e.g. https://geolens.example.com (the /api suffix is appended automatically).Required
  • GEOLENS_API_KEYAPI key, sent as X-Api-Key. Omit for public-only access. A map_author key also lets the map authoring tools create and style maps.
  • GEOLENS_TOKENJWT bearer token, used only when GEOLENS_API_KEY is unset.

Tools this server provides (9)

Taken from the project documentation; the running server may differ.

search_datasets
Find datasets
get_dataset_schema
Read a dataset's columns
get_features
Page through features
list_maps
List saved maps
get_map
Fetch a map and its layers
list_stories
List published stories
get_story
Fetch a story and its chapters
aggregate
Exact counts, statistics, histograms, group-bys and row pages over one dataset
query
One sandboxed SELECT

What it does

Dataset discovery
Search datasets and inspect their column schemas.
Feature paging
Read features from a dataset page by page.
Maps and stories
List and fetch saved maps with layers, and published stories with chapters.
Exact aggregation
Counts, statistics, histograms and group-bys over one dataset.
Sandboxed SQL
One read-only SELECT per query.
Access-scoped calls
Every call respects the caller's permissions; no write tools exist.

Good for

  • Let a coding agent inspect a dataset's columns before writing analysis code
  • Count features per borough with a group-by
  • Check which layers a saved map uses
  • Read a published story's chapters
  • Run a quick read-only SQL check against catalog data

Pricing

Open source

Apache 2.0; requires your own GeoLens instance

Prices change. Check docs.getgeolens.com before you buy.

GeoLens FAQ

Can it modify my data?

No. It has no write, ingest or admin tools.

How do I install it?

pip install geolens-mcp or uvx geolens-mcp, then set GEOLENS_INSTANCE.

Do I need an API key?

Only for non-public data; omit GEOLENS_API_KEY for public-only access.

What does a too_wide refusal mean?

The bounding box holds over 500,000 rows; narrow it.

Is GeoLens free?

Yes. GeoLens is open source, so you can use and self-host it for free.

How do I add GeoLens to Claude Code?

Run this command in your terminal: claude mcp add geolens --env GEOLENS_INSTANCE='<GEOLENS_INSTANCE>' --env GEOLENS_API_KEY='<GEOLENS_API_KEY>' --env GEOLENS_TOKEN='<GEOLENS_TOKEN>' -- uvx geolens-mcp

What are the best alternatives to GeoLens?

The closest alternatives to GeoLens are Midplane, Tutu eSIM, Shanghai Streets Travel Guide, Fifty Asks and Gangway AIS.

Alternatives to GeoLens

  1. Midplane

    MCP server

    Postgres gateway for AI agents with table grants, column masking and approval for writes

    Runs locally
    • Open source
    • 5 GitHub stars
    • Databases
  2. Tutu eSIM

    MCP server

    Live travel eSIM plans, prices and roaming costs for 190+ countries

    • 5 tools
    • Remote
    • Paid
    • Maps and travel
  3. Curated places, walking routes and areas in Shanghai, Jiangsu and Zhejiang

    • 9 tools
    • Remote
    • Free
    • Maps and travel
  4. Fifty Asks

    MCP server

    Let an agent book a free AI-visibility check or a 15-minute call for a local business

    • 10 tools
    • Remote
    • Free
    • Maps and travel
  5. Gangway AIS

    MCP server

    Vessel positions, port calls and anchorage waiting times from licensed AIS data

    • 21 tools
    • Remote
    • Freemium
    • Freight and logistics