OSM Edit

You can use the OSM Edit MCP Server to let AI assistants read, search, validate, and safely edit OpenStreetMap data. It exposes a programmable interface you connect to via MCP clients, enabling you to perform rich queries and edits with built‑in protections and a development/testing environment.

How to use

You connect to the MCP server from your MCP client. The server is designed to communicate through standard input and output with your client, so you should configure the MCP connection in your client settings rather than starting the server process by itself.

In practice you will configure your MCP client to run a local, in-process server when your development environment is ready. Use the provided client setup examples to point the client at the local command that starts the MCP server. When you test, you can run comprehensive tests to verify behavior without an external client.

To explore capabilities, you can search for places, validate coordinates, explore geographic areas, and request edits on a development server. You describe your intent in plain language and the MCP server translates that into safe OpenStreetMap actions, with authentication required for write operations.

If you want to test from the command line, you can run a full comprehensive test that exercises all features. This helps ensure every tool behaves as expected before connecting to a real client.

How to install

Prerequisites you need before installing:

• Python 3.10 or higher
• Optional: uv for fast dependency management (recommended)

# Install uv (optional but recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

Step-by-step installation flow you can follow:

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

Configuration and security

Configuration is done via environment variables. The key settings you may adjust include:

• OSM_USE_DEV_API: true to use the development API, false for production
• API_KEY: authentication key for API access
• RATE_LIMIT_PER_MINUTE: API rate limiting
• LOG_LEVEL: logging verbosity

If you plan to enable write operations, you must set up OAuth credentials. Create a development account on the dedicated OpenStreetMap developer portal, register an OAuth application, then store the credentials in your environment file.

# Example environment values
OSM_USE_DEV_API=true
API_KEY=your_api_key_here
RATE_LIMIT_PER_MINUTE=60
LOG_LEVEL=INFO

Enable write operations (optional)

To create or edit map data, you need OAuth authentication. Follow these steps to enable write access on your development server.

1. Create a Development OAuth Account

2. Register a new OAuth application with a redirect URI and all permissions

3. Add the credentials to your environment file as shown above

4. Authenticate by running the OAuth flow in your environment and verify tests pass.

Testing and test commands

You can run a quick health check or a comprehensive test suite to validate that the MCP server behaves correctly before you connect a client.

uv run python status_check.py  # Quick health check
uv run python test_comprehensive.py  # Full test suite

MCP client integration (examples)

Two common ways to run the MCP server from a client are shown here as examples. Use the method that matches your client setup.

# Example 1: using uv to run the local server from a script
{
  "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"
      }
    }
  }
}

2. Alternative: using a wrapper script if uv path issues arise. The command runs the same server but from a shell script.

# Example 2: wrapper script (path shown as an example)
{
  "mcpServers": {
    "osm_edit": {
      "command": "/path/to/osm-edit-mcp/run_mcp.sh",
      "args": [],
      "env": {
        "OSM_USE_DEV_API": "true",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Advanced deployment and operations

When deploying the MCP Server to a broader environment, you can run it in development mode locally or deploy to a server with a public URL. Ensure the environment variables are set in your deployment environment and that API keys are protected.

Health and logs are accessible through standard tooling for your environment, and you can monitor resources with your deployment platform’s built-in capabilities.

Safety and testing notes

All write operations are protected by OAuth authentication and rate limiting. The development API is used by default to provide a safe testing environment. Input validation and proper changeset management help prevent accidental or unsafe edits.

Troubleshooting

If you encounter issues when starting or testing, verify that you are using the correct MCP command and that environment variables are set. If you see authentication errors, re-run the OAuth authentication flow and confirm your credentials are correct.

Available tools

find_nearby_amenities

Find places around a location by radius and type such as restaurants, cafes, hospitals, and schools.

get_place_info

Search places by name to retrieve detailed information.

search_osm_elements

Text search for any OpenStreetMap element.

smart_geocode

Convert a postal address or place name to geographic coordinates.

validate_coordinates

Check if coordinates are valid and retrieve location information.

get_osm_elements_in_area

Retrieve all OSM elements within a defined geographic area.

get_osm_statistics

Provide statistics for an area, such as counts of amenities.

get_osm_node

Get details of a node by its ID.

get_osm_way

Get details of a way by its ID.

get_osm_relation

Get details of a relation by its ID.

create_changeset

Start an editing session for making changesets.

create_osm_node

Add a new node to the map.

create_place_from_description

Create a new place by describing it in natural language.