# OpenStreetMap MCP Server
A powerful **Model Context Protocol (MCP)** server for OpenStreetMap, providing **30 tools** for geocoding, routing, quality assurance, and data analysis. Optimized for AI assistants like Cursor and Claude.
**A community project by Grab** — providing open-source mapping tools to help developers and researchers work with OpenStreetMap data more effectively.
---
## 🎯 Quick Start
### 1️⃣ Installation
```bash
git clone https://github.com/GRABOSM/osm-mcp.git
cd osm-mcp
npm install
npm run build
```
### 2️⃣ Configure AI Integration
#### **Cursor AI**
1. Open Cursor **Settings** → **Features** → **Model Context Protocol**.
2. Add a new server with:
- **Type**: `command`
- **Command**: `node /absolute/path/to/osm-mcp/dist/index.js`
#### **Cursor Desktop**
Add this to your `mcp.json`:
```json
{
"mcpServers": {
"osm-mcp": {
"command": "node",
"args": ["/absolute/path/to/osm-mcp/dist/index.js"]
}
}
}
```
#### **Claude Desktop**
Add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"osm": {
"command": "node",
"args": ["/absolute/path/to/osm-mcp/dist/index.js"]
}
}
}
```
### 3️⃣ Start Using
Try asking your AI:
- "Find coffee shops in Makati, Manila"
- "Calculate a 15-minute driving isochrone from Grab HQ Singapore"
- "Get directions from Changi Airport to Marina Bay Sands"
---
## 🚀 Key Features
* **Geocoding**: Search addresses and landmarks globally.
* **Routing (OSRM)**: Turn-by-turn directions, distance matrices, and route optimization.
* **Smart POI**: Find restaurants, shops, and attractions with intelligent tag detection.
* **Quality Assurance (OSMOSE)**: Detect mapping errors and monitor data quality.
* **Changeset Analysis**: Analyze recent edits and user contributions.
* **Tag Intelligence (Taginfo)**: Real-world tag usage statistics and validation.
* **Dual Interface**: Use via MCP (AI tools) or HTTP REST API.
---
## 🛠️ Tool Reference (30 Tools)
### 🗺️ Geocoding (4)
1. `search_location`: Search for places and addresses.
2. `reverse_geocode`: Get address from coordinates.
3. `search_structured`: Search by street, city, country, etc.
4. `get_place_details`: Get full details of an OSM element.
### 📍 Points of Interest (3)
5. `search_pois`: General POI search (amenities, shops, etc.).
6. `search_pois_smart`: Intelligent POI search with category detection.
7. `find_amenities_nearby`: Locate facilities within a specific radius.
### 🛣️ Routing & Navigation (5)
8. `get_osrm_route`: Detailed turn-by-turn directions.
9. `get_distance_matrix`: Travel times and distances between multiple points.
10. `optimize_route`: Find the best route through multiple stops (TSP).
11. `map_match_gps`: Snap GPS traces to the road network.
12. `calculate_isochrone`: Area reachable within a time limit.
### 📊 OSM Data Analysis (6)
13. `search_highways_smart`: Smart search for roads and motorways.
14. `get_elements_in_bounds`: Get all data within a bounding box.
15. `search_by_tags`: Find elements by specific OSM tags.
16. `get_route_data`: Extract road geometry for custom use.
17. `execute_overpass_query`: Run advanced Overpass QL queries.
18. `snap_to_roads`: Find the nearest road for any point.
### 🔄 Changeset Analysis (3)
19. `get_changeset`: Details of a specific mapping edit.
20. `search_changesets`: Find edits by user, time, or location.
21. `get_changeset_diff`: View exact changes made in an edit.
### 🔍 Quality Assurance (6)
22. `osmose_search_issues`: Find data errors with filters.
23. `osmose_get_issue_details`: Details of a specific quality issue.
24. `osmose_get_issues_by_country`: Quality issues by nation.
25. `osmose_get_issues_by_user`: Issues related to a specific user.
26. `osmose_get_stats`: Data quality metrics and charts.
27. `osmose_get_items`: List of detectable issue categories.
### 🏷️ Tag Intelligence (3)
28. `get_tag_suggestions`: Autocomplete for OSM tags.
29. `get_tag_stats`: Usage statistics for any tag.
30. `validate_osm_tag`: Check if a tag combination is proper.
---
## 💡 Example Usage
### Navigation
> "Get directions from KL Sentral to Petronas Twin Towers"
### Urban Planning
> "Calculate 30-minute driving isochrone from Grab HQ Singapore"
### Quality Monitoring
> "Analyze recent mapping activity in Bengaluru"
---
## 🌐 HTTP API Mode
Run as a standalone server:
```bash
npm run dev:http
```
Access docs at: `http://localhost:8888/api/info`
---
## 🛠️ Troubleshooting
- **Absolute Paths**: Always use full paths in AI tool configurations.
- **Build First**: Ensure you run `npm run build` after any changes.
- **Node Version**: Use Node.js v18 or higher.
---
## 📄 License
This project is licensed under the **MIT License**.
---
## 🙏 Credits
- **OpenStreetMap Contributors**
- **OSRM**, **Nominatim**, **Overpass**, **OSMOSE**, **Taginfo** communities.
