OpenStreetMap (OSM) MCP Server

1# OpenStreetMap (OSM) MCP Server
2 
3An OpenStreetMap MCP server implementation that enhances LLM capabilities with location-based services and geospatial data.
4 
5## Demo
6 
7### Meeting Point Optimization
8![Meeting Point Use Case](demo/use-case-meeting.gif)
9 
10### Neighborhood Analysis
11![Neighborhood Analysis Use Case](demo/use-case-neighborhood.gif)
12 
13### Parking Search
14![Parking Search Use Case](demo/use-case-parking.gif)
15 
16 
17## Installation
18 
19### In MCP Hosts like Claude Desktop, Cursor, Windsurf, etc.
20- `osm-mcp-server`: The main server, available for public use.
21  
22  ```json
23  "mcpServers": {
24    "osm-mcp-server": {
25      "command": "uvx",
26      "args": [
27        "osm-mcp-server"
28      ]
29    }
30  }
31  ```
32 
33## Features
34 
35This server provides LLMs with tools to interact with OpenStreetMap data, enabling location-based applications to:
36 
37- Geocode addresses and place names to coordinates
38- Reverse geocode coordinates to addresses
39- Find nearby points of interest
40- Get route directions between locations
41- Search for places by category within a bounding box
42- Suggest optimal meeting points for multiple people
43- Explore areas and get comprehensive location information
44- Find schools and educational institutions near a location
45- Analyze commute options between home and work
46- Locate EV charging stations with connector and power filtering
47- Perform neighborhood livability analysis for real estate
48- Find parking facilities with availability and fee information
49 
50## Components
51 
52### Resources
53 
54The server implements location-based resources:
55- `location://place/{query}`: Get information about places by name or address
56- `location://map/{style}/{z}/{x}/{y}`: Get styled map tiles at specified coordinates
57 
58### Tools
59 
60The server implements several geospatial tools:
61- `geocode_address`: Convert text to geographic coordinates
62- `reverse_geocode`: Convert coordinates to human-readable addresses
63- `find_nearby_places`: Discover points of interest near a location
64- `get_route_directions`: Get turn-by-turn directions between locations
65- `search_category`: Find places of specific categories in an area
66- `suggest_meeting_point`: Find optimal meeting spots for multiple people
67- `explore_area`: Get comprehensive data about a neighborhood
68- `find_schools_nearby`: Locate educational institutions near a specific location
69- `analyze_commute`: Compare transportation options between home and work
70- `find_ev_charging_stations`: Locate EV charging infrastructure with filtering
71- `analyze_neighborhood`: Evaluate neighborhood livability for real estate
72- `find_parking_facilities`: Locate parking options near a destination
73 
74 
75## Local Testing
76 
77### Running the Server
78 
79To run the server locally:
80 
811. Install the package in development mode:
82 
83```bash
84pip install -e .
85```
86 
872. Start the server:
88 
89```bash
90osm-mcp-server
91```
92 
933. The server will start and listen for MCP requests on the standard input/output.
94 
95### Testing with Example Clients
96 
97The repository includes two example clients in the `examples/` directory:
98 
99#### Basic Client Example
100 
101`client.py` demonstrates basic usage of the OSM MCP server:
102 
103```bash
104python examples/client.py
105```
106 
107This will:
108- Connect to the locally running server
109- Get information about San Francisco
110- Search for restaurants in the area
111- Retrieve comprehensive map data with progress tracking
112 
113#### LLM Integration Example
114 
115`llm_client.py` provides a helper class designed for LLM integration:
116 
117```bash
118python examples/llm_client.py
119```
120 
121This example shows how an LLM can use the Location Assistant to:
122- Get location information from text queries
123- Find nearby points of interest
124- Get directions between locations
125- Find optimal meeting points
126- Explore neighborhoods
127 
128### Writing Your Own Client
129 
130To create your own client:
131 
1321. Import the MCP client:
133```python
134from mcp.client import Client
135```
136 
1372. Initialize the client with your server URL:
138```python
139client = Client("http://localhost:8000")
140```
141 
1423. Invoke tools or access resources:
143```python
144# Example: Geocode an address
145results = await client.invoke_tool("geocode_address", {"address": "New York City"})
146```
147 
148#### Claude Desktop config for local server
149 
150On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
151On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
152 
153<details>
154  <summary>Development/Unpublished Servers Configuration</summary>
155  
156  ```json
157  "mcpServers": {
158    "osm-mcp-server": {
159      "command": "uv",
160      "args": [
161        "--directory",
162        "/path/to/osm-mcp-server",
163        "run",
164        "osm-mcp-server"
165      ]
166    }
167  }
168  ```
169</details>
170 
171 
172 
173## Development
174 
175### Building and Publishing
176 
177To prepare the package for distribution:
178 
1791. Sync dependencies and update lockfile:
180```bash
181uv sync
182```
183 
1842. Build package distributions:
185```bash
186uv build
187```
188 
189This will create source and wheel distributions in the `dist/` directory.
190 
1913. Publish to PyPI:
192```bash
193uv publish
194```
195 
196Note: You'll need to set PyPI credentials via environment variables or command flags.
197 
198### Debugging
199 
200Since MCP servers run over stdio, debugging can be challenging. For the best debugging
201experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
202 
203You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:
204 
205```bash
206npx @modelcontextprotocol/inspector uv --directory /path/to/osm-mcp-server run osm-mcp-server
207```
208 
209Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
210 
211 
212 
213 
214