Overture Maps 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)

Tool	Theme	What It Does
get_place_categories	Places	Search Overture's place category taxonomy
places_in_radius	Places	Find all places matching a category within a radius
nearest_place_of_type	Places	Find the single closest place of a given type
count_places_by_type_in_radius	Places	Count places of a category in an area
building_count_in_radius	Buildings	Count buildings in an area
building_class_composition	Buildings	Get % breakdown of building types
point_in_admin_boundary	Divisions	Find what country/region/city contains a point
road_count_by_class	Transportation	Count road segments by class in an area
nearest_road_of_class	Transportation	Find the closest road of a given class
road_surface_composition	Transportation	Get % breakdown of road surface types
land_use_at_point	Land Use	Determine land use designation at a point
land_use_composition	Land Use	Get % breakdown of land use types in an area
land_use_search	Land Use	Find land use parcels of a specific subtype

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

Variable	Required	Default	Description
OVERTURE_API_KEY	For SSE/HTTP	—	Bearer token for client auth
TRANSPORT	No	stdio	stdio, sse, or http
TOOL_MODE	No	direct	direct or progressive
OVERTURE_DATA_VERSION	No	2026-01-21.0	Overture release version
MAX_CONCURRENT_QUERIES	No	3	DuckDB concurrency limit
MAX_RADIUS_M	No	50000	Safety cap on radius (meters)
PORT	No	8000	Server port (SSE/HTTP only)
HOST	No	0.0.0.0	Server host (SSE/HTTP only)

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