Overture Maps MCP Server

An open-source MCP server that exposes Overture Maps data as spatial analytics tools for AI agents.

What This Does

AI agents need geospatial intelligence. This server gives them direct access to Overture Maps data through clean, composable tool primitives.

Ask questions like:

• "What percentage of buildings within 1km are residential vs commercial?"

• "What's the land use composition — residential, industrial, or mixed-use?"

• "How does cafe density compare between two potential retail locations?"

How It Fits in the Agent Stack

+---------------------------------------------------+
|  AI Agent (Claude, Mistral, etc.)                 |
+-----------------+---------------------------------+
|  Geocoding /    |  Overture Maps MCP              |
|  Routing /      |  ----------------------         |
|  Display MCP    |  Place analytics                |
|  -------------- |  Building composition           |
|  Geocoding      |  Admin boundary lookups         |
|  Routing        |  Transportation analysis        |
|  Directions     |  Land use classification        |
|  ETA            |  Category discovery             |
|  Map display    |                                 |
+-----------------+---------------------------------+

Overture MCP handles spatial analytics that need direct data access. Geocoding/Routing/Display MCPs handle geocoding, routing, directions, and map display via APIs.

They're complementary — use them together for a complete geospatial agent.

Available Tools (V1)

The server also supports a progressive disclosure mode (TOOL_MODE=progressive) that exposes 3 meta-tools instead of 13 individual tools — useful when running alongside many other MCPs where context overhead matters. See docs/TOOLS.md for details.

See docs/OPERATIONS.md for full parameter and response specifications.

Quick Start

Prerequisites

• Python 3.10+

• An MCP-compatible AI agent (Claude Desktop, Claude Code, etc.)

Install from Source

git clone https://github.com/your-username/overture-mcp-server.git
cd overture-mcp-server
pip install -e .

Run Locally (stdio transport)

# stdio is default — no API key needed for local use
python -m overture_mcp.server

# or via the CLI entry point
overture-mcp-server

Run as Hosted Server (SSE transport)

export OVERTURE_API_KEY="your-api-key"
export TRANSPORT=sse
python -m overture_mcp.server
# Server starts on http://0.0.0.0:8000

Connect from Claude Desktop

Local (stdio): Add to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "overture-maps": {
      "command": "python",
      "args": ["-m", "overture_mcp.server"]
    }
  }
}

Remote (SSE): Connect to a hosted instance:

{
  "mcpServers": {
    "overture-maps": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Example Agent Interaction

User: "Compare cafe density near two potential retail locations in Amsterdam"

Agent:
  1. Calls Geocoding MCP -> geocode("Leidseplein, Amsterdam") -> (52.3636, 4.8828)
  2. Calls Geocoding MCP -> geocode("De Pijp, Amsterdam") -> (52.3509, 4.8936)
  3. Calls Overture MCP -> get_place_categories({query: "cafe"})
  4. Calls Overture MCP -> count_places_by_type_in_radius(
       {lat: 52.3636, lng: 4.8828, radius_m: 500, category: "cafe"}) -> 12
  5. Calls Overture MCP -> count_places_by_type_in_radius(
       {lat: 52.3509, lng: 4.8936, radius_m: 500, category: "cafe"}) -> 7
  6. Returns: "Leidseplein has 12 cafes within 500m vs 7 in De Pijp..."

Architecture

• Runtime: Python + FastMCP

• Database: DuckDB (in-process) with Spatial extension

• Data: Overture Maps GeoParquet on S3 (queried directly, no data copying)

• Auth: Bearer token via Authorization header (HTTP/SSE transports)

• Transports: stdio (local, default), SSE (hosted), Streamable HTTP (hosted)

• Hosting: Railway, Docker, or any container platform

• Tool modes: Direct (default, 13 tools) or progressive (3 meta-tools)

See ARCHITECTURE.md for full technical details and design decisions.

Data Source

This server queries Overture Maps data directly from S3.

• Current release: 2026-01-21.0

• Update frequency: Quarterly

• License: Overture Maps data is available under ODbL and CDLA Permissive 2.0

• Coverage: Global, with varying completeness by region

• No AWS credentials needed — the Overture S3 bucket is publicly accessible

Environment Variables

Documentation

• ARCHITECTURE.md — Technical architecture and all design decisions

• docs/TOOLS.md — MCP tool specifications

• docs/OPERATIONS.md — Operation catalog with full specs

• docs/DATA_MODEL.md — Overture schema reference

• docs/DEPLOYMENT.md — Railway deployment guide

Contributing

Contributions welcome! Please read the architecture doc first to understand design decisions.

# Clone and set up dev environment
git clone https://github.com/your-username/overture-mcp-server.git
cd overture-mcp-server
pip install -e ".[dev]"

# Run tests (no S3 access needed)
pytest tests/ -m "not s3"

# Run full test suite
pytest tests/

License

MIT