GeoLens
Read-only agent access to a self-hosted GeoLens spatial catalog, maps and SQL
- 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-mcpAdd 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).RequiredGEOLENS_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

Midplane
MCP serverPostgres gateway for AI agents with table grants, column masking and approval for writes
Runs locally- Open source
- 5 GitHub stars
- Databases

Tutu eSIM
MCP serverLive travel eSIM plans, prices and roaming costs for 190+ countries
- 5 tools
- Remote
- Paid
- Maps and travel

Shanghai Streets Travel Guide
MCP serverCurated places, walking routes and areas in Shanghai, Jiangsu and Zhejiang
- 9 tools
- Remote
- Free
- Maps and travel
Fifty Asks
MCP serverLet an agent book a free AI-visibility check or a 15-minute call for a local business
- 10 tools
- Remote
- Free
- Maps and travel

Gangway AIS
MCP serverVessel positions, port calls and anchorage waiting times from licensed AIS data
- 21 tools
- Remote
- Freemium
- Freight and logistics
Public tour and ticket search for Gramado, Calafate, Bariloche, Ushuaia and Cartagena
- 3 tools
- Remote
- Free
- Maps and travel