Which integrations are available for this server?

Enables interaction with OpenStreetMap data to search for places and amenities, validate geographic coordinates, explore map regions, and safely perform edits such as creating nodes and managing changesets.

How do I use OSM Edit MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OSM Edit MCP Server find coffee shops within 500m of the Empire State Building" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

OSM Edit MCP Server

PyPI version Python License: MIT Code style: black

A powerful Model Context Protocol (MCP) server that enables AI assistants to interact with OpenStreetMap data. Read, search, validate, and edit map data safely with built-in protections.

🌟 What Can You Do?

🔍 Search Places: Find restaurants, cafes, hospitals, schools, and more
📍 Validate Locations: Check coordinates and get detailed location info
🗺️ Explore Areas: Discover what's in any geographic region
✏️ Edit Safely: Make map edits on the development server first
🤖 Natural Language: Use plain English to describe what you want

📦 Prerequisites

Python 3.10+
(Optional) uv for fast dependency management
# Install uv (optional but recommended) curl -LsSf https://astral.sh/uv/install.sh | sh

🚀 Quick Start (5 Minutes)

1️⃣ Install

git clone https://github.com/skywinder/osm-edit-mcp cd osm-edit-mcp uv sync --dev # Installs both base and development dependencies

2️⃣ Configure

cp .env.example .env # No need to edit - defaults are ready to use!

3️⃣ Test

uv run python status_check.py

4️⃣ Connect to MCP Client

Important: MCP servers communicate via stdin/stdout with MCP clients. Don't run main.py directly!

Instead, configure the server in your MCP client:

Cursor IDE: Settings → Features → MCP
Claude Desktop: See MCP Client Setup
VSCode (Cline): Add to settings.json

To test functionality without a client:

uv run python test_comprehensive.py

🔐 Enable Write Operations (Optional)

To create or edit map data, you need OAuth authentication:

Step 1: Create Dev Account

Visit https://api06.dev.openstreetmap.org and sign up (separate from main OSM).

Step 2: Create OAuth App

Go to your dev account settings → OAuth 2 Applications
Register new application:
- Name: OSM Edit MCP Dev
- Redirect URI: https://localhost:8080/callback
- Permissions: Select all checkboxes

Step 3: Add Credentials

Edit .env and add your OAuth credentials:

OSM_DEV_CLIENT_ID=your_client_id_here OSM_DEV_CLIENT_SECRET=your_client_secret_here

Step 4: Authenticate

uv run python oauth_auth.py

Step 5: Verify

uv run python test_comprehensive.py

Expected: ✅ 19/19 tests passing

📖 Available Tools

🔍 Search & Discovery

Tool	Description	Example
`find_nearby_amenities`	Find places around a location	"Find restaurants within 500m"
`get_place_info`	Search places by name	"Where is Central Park?"
`search_osm_elements`	Text search for any element	"Search for coffee shops"
`smart_geocode`	Convert address to coordinates	"10 Downing Street, London"

📍 Location Tools

Tool	Description	Example
`validate_coordinates`	Check if coordinates are valid	`51.5074, -0.1278`
`get_osm_elements_in_area`	Get all elements in a box	"What's in this area?"
`get_osm_statistics`	Area statistics	"How many restaurants?"

🗺️ OSM Data Access

Tool	Description	Example
`get_osm_node`	Get node by ID	Node details
`get_osm_way`	Get way by ID	Street/building info
`get_osm_relation`	Get relation by ID	Complex features

✏️ Editing Tools (Requires Auth)

Tool	Description	Example
`create_changeset`	Start editing session	Required for edits
`create_osm_node`	Add new point	"Add restaurant here"
`create_place_from_description`	Natural language creation	"Add coffee shop called Bean There at..."

💡 Usage Examples

Find Nearby Restaurants

# Find Italian restaurants near the Colosseum result = await find_nearby_amenities( lat=41.8902, lon=12.4922, radius_meters=500, amenity_type="restaurant" )

Validate Coordinates

# Check if coordinates are valid and get location info result = await validate_coordinates(51.5074, -0.1278) # Returns: "London, England, United Kingdom"

Natural Language Search

# Parse natural language requests result = await parse_natural_language_osm_request( "Find coffee shops near the Eiffel Tower" )

🖥️ MCP Client Integration

Quick Setup for Popular Clients

// With uv (Recommended) { "mcpServers": { "osm-edit": { "command": "uv", "args": ["run", "python", "main.py"], "cwd": "/path/to/osm-edit-mcp", "env": { "OSM_USE_DEV_API": "true", "LOG_LEVEL": "INFO" } } } } // Alternative: Using wrapper script (if uv has path issues) { "mcpServers": { "osm-edit": { "command": "/path/to/osm-edit-mcp/run_mcp.sh", "args": [], "env": { "OSM_USE_DEV_API": "true", "LOG_LEVEL": "INFO" } } } }

Add to Cursor Settings → Features → MCP

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)

{ "mcpServers": [ { "name": "osm-edit", "command": "uv", "args": ["run", "python", "main.py"], "cwd": "/path/to/osm-edit-mcp" } ] }

Add to ~/.continue/config.json

{ "cline.mcpServers": { "osm-edit": { "command": "uv", "args": ["run", "python", "main.py"], "cwd": "./osm-edit-mcp" } } }

Add to VSCode settings or .vscode/settings.json

📖 Full MCP Client Setup Guide - Detailed instructions for all clients

Example Queries

"Find restaurants near Times Square"
"What's at coordinates 48.8584, 2.2945?"
"Search for hospitals in Seattle"

🛡️ Safety Features

✅ Development API by default - Safe testing environment
✅ OAuth protection - Edits require authentication
✅ Rate limiting - Respects API limits
✅ Input validation - Prevents invalid data
✅ Changeset management - Groups edits properly

📊 Project Status

Version: 0.1.0
Tests: 100% passing (19/19)
Python: 3.10+
License: MIT

🌐 Remote Deployment (Make it Accessible Anywhere)

The OSM Edit MCP Server can be deployed as a web service accessible from anywhere. This is useful for:

Team collaboration
Integration with web applications
Running on cloud servers
Access from multiple devices

🚀 Quick Deploy with Docker

1. Prerequisites

Docker and docker-compose installed
A server with public IP or domain name
SSL certificate (or use the self-signed cert for testing)

2. Deploy Steps

# Clone the repository git clone https://github.com/skywinder/osm-edit-mcp cd osm-edit-mcp # Configure environment cp .env.example .env # Edit .env with your OAuth credentials and API_KEY # Deploy with Docker chmod +x deploy.sh ./deploy.sh

The deploy script will:

Build Docker containers
Generate SSL certificates (self-signed for development)
Start the web server on port 8000
Set up Nginx reverse proxy on port 443

3. Access Your Server

After deployment, access your server at:

https://your-server-ip/ (with Nginx SSL)
http://your-server-ip:8000/ (direct access)
API docs: http://your-server-ip:8000/docs

📡 API Usage

All MCP functionality is exposed via REST API endpoints. Authenticate with your API key:

# Example: Find nearby amenities curl -X POST https://your-server-ip/api/nearby-amenities \ -H "Authorization: Bearer your-api-key-here" \ -H "Content-Type: application/json" \ -d '{ "lat": 51.5074, "lon": -0.1278, "radius_meters": 500, "amenity_type": "restaurant" }'

🔐 Security Configuration

API Key: Set a strong API_KEY in your .env file
SSL Certificate: Replace self-signed cert with a real one for production
Firewall: Only expose necessary ports (80, 443)
Rate Limiting: Configured via RATE_LIMIT_PER_MINUTE in .env

☁️ Cloud Platform Deployment

# Launch EC2 instance (Ubuntu 22.04 recommended) # Install Docker sudo apt update sudo apt install docker.io docker-compose # Clone and deploy git clone https://github.com/skywinder/osm-edit-mcp cd osm-edit-mcp sudo ./deploy.sh

# Create a Droplet with Docker pre-installed # SSH into your droplet ssh root@your-droplet-ip # Clone and deploy git clone https://github.com/skywinder/osm-edit-mcp cd osm-edit-mcp ./deploy.sh

# Build and push to Container Registry gcloud builds submit --tag gcr.io/PROJECT-ID/osm-edit-mcp # Deploy to Cloud Run gcloud run deploy osm-edit-mcp \ --image gcr.io/PROJECT-ID/osm-edit-mcp \ --platform managed \ --allow-unauthenticated \ --set-env-vars API_KEY=your-api-key

🔧 Advanced Configuration

Custom Domain & SSL

# Update nginx.conf with your domain server_name yourdomain.com; # Use Let's Encrypt for free SSL sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d yourdomain.com

Environment Variables

All configuration is done via environment variables. Key settings:

OSM_USE_DEV_API: Use dev (true) or production (false) API
API_KEY: Authentication key for API access
RATE_LIMIT_PER_MINUTE: API rate limiting
LOG_LEVEL: Logging verbosity

Monitoring

# View logs docker-compose logs -f # Check health curl https://your-server/health # Monitor resources docker stats

📊 Production Checklist

Use production OSM API (OSM_USE_DEV_API=false)
Set strong API_KEY
Install real SSL certificate
Configure firewall rules
Set up monitoring/alerts
Enable automated backups
Configure log rotation
Set resource limits in docker-compose.yml

🧪 Testing

# Quick test python quick_test.py # Full test suite python test_comprehensive.py # Check your edits # Visit: https://api06.dev.openstreetmap.org/user/YOUR_USERNAME/history

🚨 Troubleshooting

Issue	Solution
"Server hangs" when running main.py	This is normal! MCP servers wait for client input. Use `uv run python test_comprehensive.py` instead
"401 Unauthorized"	Run `uv run python oauth_auth.py`
"Client auth failed"	Check OAuth credentials in `.env`
Import errors	Run `uv sync --dev`
Can't see changesets	Check dev server URL (not main OSM)
uv: command not found	Install uv: `curl -LsSf https://astral.sh/uv/install.sh \| sh`
How do I use the server?	Configure in MCP client or run `uv run python explain_mcp_server.py`

📚 Documentation

Quick Reference Card - All commands on one page
MCP Client Setup - Cursor, Claude, VSCode, etc.
Running the Server - Background, monitoring, auto-restart
Quick Start Guide
API Examples
OSM Tagging Guide
Contributing
Security Policy

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

🔗 Links

Ready to explore the world's map data? Start with the Quick Start above! 🌍