open-streetmap-mcp-v2

OpenStreetMap (OSM) MCP Server v2

An OpenStreetMap MCP server implementation that enhances LLM capabilities with location-based services and geospatial data.

This is a maintained fork. The original project is jagan-shanmugam/open-streetmap-mcp by Jagan Shanmugam, who designed and wrote all of the tools here. Upstream has had no commits since July 2025 and no longer starts against the current mcp SDK, so this fork exists to keep it working and to review and land community contributions. Issues and pull requests are welcome.

What changed in v2

• Works with mcp 2.x. The SDK renamed FastMCP to MCPServer; uvx osm-mcp-server now fails at import. This fork targets mcp>=2.0.
• Fixed Overpass 406 Not Acceptable. overpass-api.de rejects the old User-Agent; every request now sends osm-mcp-server-v2/<version>.
• Fixed search_category with subcategories (upstream #6 by Jagan Shanmugam): Overpass QL has no or inside a tag filter; a regex filter is used instead.
• Gemini CLI compatibility (upstream #13 by wb1016): suggest_meeting_point takes a typed {latitude, longitude} model so the schema has no additionalProperties.
• HTTP transport and Docker (upstream #10 by robertlestak and #11 by JumpLink): --transport stdio|sse|streamable-http, --host, --port, plus a Dockerfile.
• Progress and log messages from tools are now actually delivered (they were never awaited).
• OVERPASS_API_URL lets you point at an Overpass mirror or self-hosted instance.
• Tests (uv run pytest) and CI.

Demo

Meeting Point Optimization

Neighborhood Analysis

Parking Search

Installation

In MCP Hosts like Claude Desktop, Cursor, Windsurf, etc.

• Requires Python 3.13+ and uv.

  "mcpServers": {
    "osm-mcp-server": {
      "command": "uvx",
      "args": [
        "osm-mcp-server-v2"
      ]
    }
  }
  

  Until the package is on PyPI, run it straight from GitHub:

  "mcpServers": {
    "osm-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ogSINGH/open-streetmap-mcp-v2",
        "osm-mcp-server"
      ]
    }
  }
  

HTTP transport

osm-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000

The MCP endpoint is then http://127.0.0.1:8000/mcp. --transport sse is also available. The server binds to localhost by default; there is no authentication, so only expose it on 0.0.0.0 behind something that adds it.

Docker

docker build -t osm-mcp-server-v2 .
docker run -p 8000:8000 osm-mcp-server-v2
# custom port
docker run -p 3004:3004 -e PORT=3004 osm-mcp-server-v2

The image serves Streamable HTTP on 0.0.0.0:$PORT (default 8000) as a non-root user.

Configuration

Variable	Default	Purpose
OVERPASS_API_URL	https://overpass-api.de/api/interpreter	Overpass endpoint. The public instance rate-limits aggressively; point this at a mirror (for example https://overpass.openstreetmap.fr/api/interpreter) or your own instance for heavy use.
OSM_REQUEST_TIMEOUT	60	Per-request timeout in seconds for all upstream HTTP calls.

MCP hosts launch the server as a subprocess and forward only a minimal environment, so set these in the host config rather than your shell:

"osm-mcp-server": {
  "command": "uvx",
  "args": ["osm-mcp-server-v2"],
  "env": { "OVERPASS_API_URL": "https://overpass.openstreetmap.fr/api/interpreter" }
}

All requests to Nominatim, Overpass, OSRM and the tile servers carry a User-Agent of osm-mcp-server-v2/<version>, as their usage policies require.

Features

This server provides LLMs with tools to interact with OpenStreetMap data, enabling location-based applications to:

• Geocode addresses and place names to coordinates
• Reverse geocode coordinates to addresses
• Find nearby points of interest
• Get route directions between locations
• Search for places by category within a bounding box
• Suggest optimal meeting points for multiple people
• Explore areas and get comprehensive location information
• Find schools and educational institutions near a location
• Analyze commute options between home and work
• Locate EV charging stations with connector and power filtering
• Perform neighborhood livability analysis for real estate
• Find parking facilities with availability and fee information

Components

Resources

The server implements location-based resources:

• location://place/{query}: Get information about places by name or address
• location://map/{style}/{z}/{x}/{y}: Get styled map tiles at specified coordinates

Tools

The server implements several geospatial tools:

• geocode_address: Convert text to geographic coordinates
• reverse_geocode: Convert coordinates to human-readable addresses
• find_nearby_places: Discover points of interest near a location
• get_route_directions: Get turn-by-turn directions between locations
• search_category: Find places of specific categories in an area
• suggest_meeting_point: Find optimal meeting spots for multiple people
• explore_area: Get comprehensive data about a neighborhood
• find_schools_nearby: Locate educational institutions near a specific location
• analyze_commute: Compare transportation options between home and work
• find_ev_charging_stations: Locate EV charging infrastructure with filtering
• analyze_neighborhood: Evaluate neighborhood livability for real estate
• find_parking_facilities: Locate parking options near a destination

Local Testing

Running the Server

To run the server locally:

1. Install dependencies (creates .venv):

uv sync

2. Run the tests:

uv run pytest

3. Start the server over stdio:

uv run osm-mcp-server

Testing with Example Clients

The repository includes two example clients in the examples/ directory:

Basic Client Example

client.py demonstrates basic usage of the OSM MCP server:

uv run python examples/client.py

This will:

• Connect to the locally running server
• Get information about San Francisco
• Search for restaurants in the area
• Retrieve comprehensive map data with progress tracking

LLM Integration Example

location_assistant_client.py provides a helper class designed for LLM integration:

uv run python examples/location_assistant_client.py

This example shows how an LLM can use the Location Assistant to:

• Get location information from text queries
• Find nearby points of interest
• Get directions between locations
• Find optimal meeting points
• Explore neighborhoods

Writing Your Own Client

See examples/client.py: it spawns the server over stdio with mcp.client.stdio.stdio_client, wraps it in ClientSession, and calls tools with session.call_tool(name, arguments).

Claude Desktop config for local server

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "osm-mcp-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/osm-mcp-server",
      "run",
      "osm-mcp-server"
    ]
  }
}

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI: push a v* tag. .github/workflows/publish-to-pypi.yml builds and publishes with PyPI trusted publishing (no token needed once the publisher is configured on PyPI for this repo).

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/osm-mcp-server run osm-mcp-server

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Credits

• Jagan Shanmugam (@jagan-shanmugam) — original author of open-streetmap-mcp, including every tool and resource here.
• Contributors whose upstream pull requests were reviewed and adapted into v2: Sesame2 (#7, superseded by #6), robertlestak (#10), JumpLink (#11), wb1016 (#13).
• Maintained by @ogSINGH.

Licensed under the MIT License, same as upstream. See LICENSE.