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

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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