# OpenStreetMap (OSM) MCP Server v2

[![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)

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](https://github.com/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](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.
- **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`.
- **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`.
- 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
![Meeting Point Use Case](demo/use-case-meeting.gif)

### Neighborhood Analysis
![Neighborhood Analysis Use Case](demo/use-case-neighborhood.gif)

### Parking Search
![Parking Search Use Case](demo/use-case-parking.gif)


## Installation

### In MCP Hosts like Claude Desktop, Cursor, Windsurf, etc.
- Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/).

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

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

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

### HTTP transport

```bash
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

```bash
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:

```json
"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`):

```bash
uv sync
```

2. Run the tests:

```bash
uv run pytest
```

3. Start the server over stdio:

```bash
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:

```bash
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:

```bash
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`

<details>
  <summary>Development/Unpublished Servers Configuration</summary>
  
  ```json
  "mcpServers": {
    "osm-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/osm-mcp-server",
        "run",
        "osm-mcp-server"
      ]
    }
  }
  ```
</details>



## Development

### Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:
```bash
uv sync
```

2. Build package distributions:
```bash
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](https://github.com/modelcontextprotocol/inspector).

You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:

```bash
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](https://github.com/jagan-shanmugam)) — original author of
  [open-streetmap-mcp](https://github.com/jagan-shanmugam/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](https://github.com/ogSINGH).

Licensed under the MIT License, same as upstream. See [LICENSE](LICENSE).