How jagan-shanmugam/open-streetmap-mcp works
Project type and purpose
• This is a standalone MCP (Model Context Protocol) server written in Python. It acts as a middleware between an LLM-based host (e.g., Claude Desktop, Cursor) and OpenStreetMap (OSM) data sources. The server exposes “tools” (geocode, reverse geocode, route, etc.) and “resources” (tile endpoints) over the MCP protocol via stdio or HTTP (using the UVX runner).
File structure
• Top-level:
• .github/workflows/publish-to-pypi.yml: CI/CD to publish the package
• pyproject.toml & uv.lock: build and dependency management
• LICENSE, .gitignore, README.md
• demo and examples: usage walkthroughs and sample clients
• src/osm_mcp_server/
• server.py: entry point that registers MCP tools and resource handlers
• __init__.py: package metadata
• There are no separate “frontend” or “database” directories, confirming it’s a single server process.
README for additional insights
• The server implements two categories:
a. Resources under location://… for map tiles and place lookups
b. Tools (geocode, find_nearby_places, suggest_meeting_point, etc.)
• It runs via the osm-mcp-server console script, listening over stdio/HTTP, and communicates with external OSM APIs.
a. Main Components
1. MCP Host / Client – e.g., Claude Desktop or a custom Python client
2. MCP Protocol Layer – stdio or HTTP adapter (UVX runner)
3. OSM MCP Server Process
• Tool Registry & Dispatcher – maps MCP calls to Python handlers
• Resource Handlers – tile server endpoints, place lookup
• Core Services – geocoding, routing, POI search, neighborhood analysis
• Request/Response Serializer – JSON over stdio/HTTP
4. External Services
• OpenStreetMap Overpass API (places, POIs)
• Tile servers (map tiles)
• (Optional) Caching layer or local tile cache
b. Relationships & Interactions
• The MCP Host sends JSON RPC requests to the MCP Protocol Layer.
• The Protocol Layer forwards to the Tool Registry in the Server Process.
• Tool handlers call external OSM services (Overpass, tile servers) and process results.
• Responses flow back up: Handlers → Protocol Layer → MCP Host.
• Example clients in examples/ illustrate usage of this flow.
c. Architectural Patterns & Principles
• Pipe & Filter: each tool is a filter that transforms input parameters into geospatial data
• Adapter: the Protocol Layer adapts stdio/HTTP to internal function calls
• Registry/Dispatcher: dynamic registration of tools and resources at startup
• Separation of Concerns: tools (business logic) vs. protocol vs. external I/O
d. Key Technologies & Frameworks
• Python 3 with uv command runner (UVX)
• MCP protocol spec for tool/resource invocation
• Requests or HTTPX for external OSM API calls
• JSON serialization