Skip to main content
Glama
skywinder

OSM Edit MCP Server

by skywinder
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

OSM Edit MCP Server

CI 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

  1. Go to your dev account settings → OAuth 2 Applications

  2. 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

You can also configure dev and prod entries directly in ~/.cursor/mcp.json using the provided wrapper script run_mcp.sh.

{
  "mcpServers": {
    "osm-edit-dev": {
      "command": "/Users/pk/repo/_mine/osm-edit-mcp/run_mcp.sh",
      "args": [],
      "env": {
        "OSM_USE_DEV_API": "true",
        "LOG_LEVEL": "INFO",
        "DEVELOPMENT_MODE": "true"
      },
      "enabled": false,
      "_comment": "OSM Edit MCP Server - Development (safe testing with api06.dev.openstreetmap.org)"
    },
    "osm-edit-prod": {
      "command": "/Users/pk/repo/_mine/osm-edit-mcp/run_mcp.sh",
      "args": [],
      "env": {
        "OSM_USE_DEV_API": "false",
        "LOG_LEVEL": "INFO",
        "DEVELOPMENT_MODE": "false"
      },
      "enabled": false,
      "_comment": "OSM Edit MCP Server - Production (uses api.openstreetmap.org). Use with extreme caution; write operations require OAuth and explicit confirmation."
    }
  }
}

Tip: Replace the absolute path with your local path as needed. Keep production entry disabled until you are fully configured and understand the risks.

// 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 ~/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

  1. API Key: Set a strong API_KEY in your .env file

  2. SSL Certificate: Replace self-signed cert with a real one for production

  3. Firewall: Only expose necessary ports (80, 443)

  4. 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

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

🔗 Links

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/skywinder/osm-edit-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server