# GeoLens

> GeoLens is an open-source MCP server for databases. Read-only agent access to a self-hosted GeoLens spatial catalog, maps and SQL. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://docs.getgeolens.com
- **Repository:** https://github.com/geolens-io/geolens/tree/HEAD/mcp
- **MCP Registry name:** io.github.geolens-io/geolens
- **Categories:** databases, maps and travel
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```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>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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

## 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

- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Tutu eSIM](https://ai-powered.com/mcp/tutu-esim): Tutu eSIM is a paid MCP server for maps and travel.
- [Shanghai Streets Travel Guide](https://ai-powered.com/mcp/shanghai-streets-travel-guide): Shanghai Streets Travel Guide is a free MCP server for maps and travel.
- [Fifty Asks](https://ai-powered.com/mcp/fifty-asks): Fifty Asks is a free MCP server for maps and travel.
- [Gangway AIS](https://ai-powered.com/mcp/gangway-ais): Gangway AIS is a freemium MCP server for freight and logistics.
- [Tickets: tours and event tickets in South America](https://ai-powered.com/mcp/tickets-tours-and-event-tickets-in-south-america): Tickets: tours and event tickets in South America is a free MCP server for maps and travel.
- [Goyondo](https://ai-powered.com/mcp/goyondo-2): Goyondo is a freemium MCP server for maps and travel.
- [DalVivo](https://ai-powered.com/mcp/dalvivo): DalVivo is a free MCP server for maps and travel.

---
Source: https://ai-powered.com/mcp/geolens
