{"id":"c2ed1387-1683-4747-9316-08c0ec000da2","slug":"open-streetmap-mcp-v2","kind":"mcp","name":"open-streetmap-mcp-v2","summary":"OpenStreetMap MCP server v2: maintained fork of jagan-shanmugam/open-streetmap-mcp, working with mcp 2.x","owner":"ogSINGH","repoUrl":"https://github.com/ogSINGH/open-streetmap-mcp-v2","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-11T03:24:07.000Z","addedAt":"2026-10-21T05:09:53.882Z","logoUrl":"https://avatars.githubusercontent.com/u/50068886?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":["geocoding","openstreetmap","overpass-api","python"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T02:31:03.344Z","sample":false,"url":"https://conduits.dev/tools/open-streetmap-mcp-v2","language":"Python","transports":["stdio"],"install":{"pypi":"osm-mcp-server-v2"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# OpenStreetMap (OSM) MCP Server v2\n\n[![CI](https://github.com/ogSINGH/open-streetmap-mcp-v2/actions/workflows/ci.yml/badge.svg)](https://github.com/ogSINGH/open-streetmap-mcp-v2/actions/workflows/ci.yml)\n\nAn OpenStreetMap MCP server implementation that enhances LLM capabilities with location-based services and geospatial data.\n\n> **This is a maintained fork.** The original project is\n> [jagan-shanmugam/open-streetmap-mcp](https://github.com/jagan-shanmugam/open-streetmap-mcp) by\n> **Jagan Shanmugam**, who designed and wrote all of the tools here. Upstream has had no commits since\n> July 2025 and no longer starts against the current `mcp` SDK, so this fork exists to keep it working\n> and to review and land community contributions. Issues and pull requests are welcome.\n\n## What changed in v2\n\n- **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`.\n- **Fixed Overpass `406 Not Acceptable`.** overpass-api.de rejects the old `User-Agent`; every request now sends `osm-mcp-server-v2/<version>`.\n- **Fixed `search_category` with subcategories** (upstream [#6](https://github.com/jagan-shanmugam/open-streetmap-mcp/pull/6) by Jagan Shanmugam): Overpass QL has no `or` inside a tag filter; a regex filter is used instead.\n- **Gemini CLI compatibility** (upstream [#13](https://github.com/jagan-shanmugam/open-streetmap-mcp/pull/13) by wb1016): `suggest_meeting_point` takes a typed `{latitude, longitude}` model so the schema has no `additionalProperties`.\n- **HTTP transport and Docker** (upstream [#10](https://github.com/jagan-shanmugam/open-streetmap-mcp/pull/10) by robertlestak and [#11](https://github.com/jagan-shanmugam/open-streetmap-mcp/pull/11) by JumpLink): `--transport stdio|sse|streamable-http`, `--host`, `--port`, plus a `Dockerfile`.\n- Progress and log messages from tools are now actually delivered (they were never awaited).\n- `OVERPASS_API_URL` lets you point at an Overpass mirror or self-hosted instance.\n- Tests (`uv run pytest`) and CI.\n\n## Demo\n\n### Meeting Point Optimization\n![Meeting Point Use Case](demo/use-case-meeting.gif)\n\n### Neighborhood Analysis\n![Neighborhood Analysis Use Case](demo/use-case-neighborhood.gif)\n\n### Parking Search\n![Parking Search Use Case](demo/use-case-parking.gif)\n\n\n## Installation\n\n### In MCP Hosts like Claude Desktop, Cursor, Windsurf, etc.\n- Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).\n\n  ```json\n  \"mcpServers\": {\n    \"osm-mcp-server\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"osm-mcp-server-v2\"\n      ]\n    }\n  }\n  ```\n\n  Until the package is on PyPI, run it straight from GitHub:\n\n  ```json\n  \"mcpServers\": {\n    \"osm-mcp-server\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/ogSINGH/open-streetmap-mcp-v2\",\n        \"osm-mcp-server\"\n      ]\n    }\n  }\n  ```\n\n### HTTP transport\n\n```bash\nosm-mcp-server --transport streamable-http --host 127.0.0.1 --port 8000\n```\n\nThe MCP endpoint is then `http://127.0.0.1:8000/mcp`. `--transport sse` is also available. The server binds to\nlocalhost by default; there is no authentication, so only expose it on `0.0.0.0` behind something that adds it.\n\n### Docker\n\n```bash\ndocker build -t osm-mcp-server-v2 .\ndocker run -p 8000:8000 osm-mcp-server-v2\n# custom port\ndocker run -p 3004:3004 -e PORT=3004 osm-mcp-server-v2\n```\n\nThe image serves Streamable HTTP on `0.0.0.0:$PORT` (default 8000) as a non-root user.\n\n### Configuration\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `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. |\n| `OSM_REQUEST_TIMEOUT` | `60` | Per-request timeout in seconds for all upstream HTTP calls. |\n\nMCP hosts launch the server as a subprocess and forward only a minimal environment, so set these in the host config rather than your shell:\n\n```json\n\"osm-mcp-server\": {\n  \"command\": \"uvx\",\n  \"args\": [\"osm-mcp-server-v2\"],\n  \"env\": { \"OVERPASS_API_URL\": \"https://overpass.openstreetmap.fr/api/interpreter\" }\n}\n```\n\nAll requests to Nominatim, Overpass, OSRM and the tile servers carry a `User-Agent` of `osm-mcp-server-v2/<version>`, as their usage policies require.\n\n## Features\n\nThis server provides LLMs with tools to interact with OpenStreetMap data, enabling location-based applications to:\n\n- Geocode addresses and place names to coordinates\n- Reverse geocode coordinates to addresses\n- Find nearby points of interest\n- Get route directions between locations\n- Search for places by category within a bounding box\n- Suggest optimal meeting points for multiple people\n- Explore areas and get comprehensive location information\n- Find schools and educational institutions near a location\n- Analyze commute options between home and work\n- Locate EV charging stations with connector and power filtering\n- Perform neighborhood livability analysis for real estate\n- Find parking facilities with availability and fee information\n\n## Components\n\n### Resources\n\nThe server implements location-based resources:\n- `location://place/{query}`: Get information about places by name or address\n- `location://map/{style}/{z}/{x}/{y}`: Get styled map tiles at specified coordinates\n\n### Tools\n\nThe server implements several geospatial tools:\n- `geocode_address`: Convert text to geographic coordinates\n- `reverse_geocode`: Convert coordinates to human-readable addresses\n- `find_nearby_places`: Discover points of interest near a location\n- `get_route_directions`: Get turn-by-turn directions between locations\n- `search_category`: Find places of specific categories in an area\n- `suggest_meeting_point`: Find optimal meeting spots for multiple people\n- `explore_area`: Get comprehensive data about a neighborhood\n- `find_schools_nearby`: Locate educational institutions near a specific location\n- `analyze_commute`: Compare transportation options between home and work\n- `find_ev_charging_stations`: Locate EV charging infrastructure with filtering\n- `analyze_neighborhood`: Evaluate neighborhood livability for real estate\n- `find_parking_facilities`: Locate parking options near a destination\n\n\n## Local Testing\n\n### Running the Server\n\nTo run the server locally:\n\n1. Install dependencies (creates `.venv`):\n\n```bash\nuv sync\n```\n\n2. Run the tests:\n\n```bash\nuv run pytest\n```\n\n3. Start the server over stdio:\n\n```bash\nuv run osm-mcp-server\n```\n\n### Testing with Example Clients\n\nThe repository includes two example clients in the `examples/` directory:\n\n#### Basic Client Example\n\n`client.py` demonstrates basic usage of the OSM MCP server:\n\n```bash\nuv run python examples/client.py\n```\n\nThis will:\n- Connect to the locally running server\n- Get information about San Francisco\n- Search for restaurants in the area\n- Retrieve comprehensive map data with progress tracking\n\n#### LLM Integration Example\n\n`location_assistant_client.py` provides a helper class designed for LLM integration:\n\n```bash\nuv run python examples/location_assistant_client.py\n```\n\nThis example shows how an LLM can use the Location Assistant to:\n- Get location information from text queries\n- Find nearby points of interest\n- Get directions between locations\n- Find optimal meeting points\n- Explore neighborhoods\n\n### Writing Your Own Client\n\nSee `examples/client.py`: it spawns the server over stdio with `mcp.client.stdio.stdio_client`,\nwraps it in `ClientSession`, and calls tools with `session.call_tool(name, arguments)`.\n\n#### Claude Desktop config for local server\n\nOn MacOS: `~/Library/Application\\ Support/Claude/claude_desktop_config.json`\nOn Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n<details>\n  <summary>Development/Unpublished Servers Configuration</summary>\n  \n  ```json\n  \"mcpServers\": {\n    \"osm-mcp-server\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/osm-mcp-server\",\n        \"run\",\n        \"osm-mcp-server\"\n      ]\n    }\n  }\n  ```\n</details>\n\n\n\n## Development\n\n### Building and Publishing\n\nTo prepare the package for distribution:\n\n1. Sync dependencies and update lockfile:\n```bash\nuv sync\n```\n\n2. Build package distributions:\n```bash\nuv build\n```\n\nThis will create source and wheel distributions in the `dist/` directory.\n\n3. Publish to PyPI: push a `v*` tag. `.github/workflows/publish-to-pypi.yml` builds and publishes with\nPyPI trusted publishing (no token needed once the publisher is configured on PyPI for this repo).\n\n### Debugging\n\nSince MCP servers run over stdio, debugging can be challenging. For the best debugging\nexperience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).\n\nYou can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory /path/to/osm-mcp-server run osm-mcp-server\n```\n\nUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.\n\n\n\n\n\n## Credits\n\n- **Jagan Shanmugam** ([@jagan-shanmugam](https://github.com/jagan-shanmugam)) — original author of\n  [open-streetmap-mcp](https://github.com/jagan-shanmugam/open-streetmap-mcp), including every tool and resource here.\n- Contributors whose upstream pull requests were reviewed and adapted into v2: Sesame2 (#7, superseded by #6),\n  robertlestak (#10), JumpLink (#11), wb1016 (#13).\n- Maintained by [@ogSINGH](https://github.com/ogSINGH).\n\nLicensed under the MIT License, same as upstream. See [LICENSE](LICENSE).\n"}