osmmcp

OpenStreetMap MCP Server (Go Implementation)

This is a Go implementation of the OpenStreetMap MCP server that enhances LLM capabilities with location-based services and geospatial data.

Overview

This project is a Go OpenStreetMap MCP server. It implemets the Model Context Protocol to enable LLMs to interact with geospatial data.

We've reimplemented the functionality in Go with a focus on performance, maintainability, and ease of integration with MCP desktop clients.

Features

The server provides LLMs with tools to interact with OpenStreetMap data, including:

• Geocoding addresses and place names to coordinates
• Reverse geocoding coordinates to addresses
• Finding nearby points of interest
• Getting route directions between locations
• Searching for places by category within a bounding box
• Suggesting optimal meeting points for multiple people
• Exploring areas and getting comprehensive location information
• Finding EV charging stations near a location
• Finding EV charging stations along a route
• Analyzing commute options between home and work
• Performing neighborhood livability analysis
• Finding schools near a location
• Finding parking facilities

Implemented Tools

Code Architecture and Design

The code follows software engineering best practices:

1. High Cohesion, Low Coupling - Each package has a clear, focused responsibility
2. Separation of Concerns - Tools, server logic, and utilities are cleanly separated
3. DRY (Don't Repeat Yourself) - Common utilities are extracted into the pkg/osm package
4. Security First - HTTP clients are properly configured with timeouts and connection limits
5. Structured Logging - All logging is done via slog with consistent levels and formats:
   • Debug: Developer detail, verbose or diagnostic messages
   • Info: Routine operational messages
   • Warn: Unexpected conditions that don't necessarily halt execution
   • Error: Critical problems, potential or actual failures
6. SOLID Principles - Particularly Single Responsibility and Interface Segregation
7. Registry Pattern - All tools are defined in a central registry for improved maintainability
8. Google Polyline5 Format - Standardized polyline encoding/decoding using Google's Polyline5 format
9. Precise Geospatial Calculations - Accurate Haversine distance calculations with appropriate tolerances
10. Context-Aware Operations - All operations properly handle context for cancellation and timeouts

Usage

Requirements

• Go 1.24 or higher
• OpenStreetMap API access (no API key required, but rate limits apply)

Building the server

go build -o osmmcp ./cmd/osmmcp

Running the server

./osmmcp

The server supports several command-line flags:

# Show version information
./osmmcp --version

# Enable debug logging
./osmmcp --debug

# Generate a Claude Desktop Client configuration file
./osmmcp --generate-config /path/to/config.json

# Customize rate limits (requests per second)
./osmmcp --nominatim-rps 1.0 --nominatim-burst 1
./osmmcp --overpass-rps 1.0 --overpass-burst 1
./osmmcp --osrm-rps 1.0 --osrm-burst 1

# Set custom User-Agent string
./osmmcp --user-agent "MyApp/1.0"

Logging Configuration

The server uses structured logging via slog with the following configuration:

• Debug level: Enabled with --debug flag
• Default level: Info
• Format: Text-based with key-value pairs
• Output: Standard error (stderr)

Example log output:

2024-03-14T10:15:30.123Z INFO starting OpenStreetMap MCP server version=0.1.0 log_level=info user_agent=osm-mcp-server/0.1.0
2024-03-14T10:15:30.124Z DEBUG rate limiter initialized service=nominatim rps=1.0 burst=1

The server will start and listen for MCP requests on the standard input/output. You can use it with any MCP-compatible client or LLM integration.

Using with Claude Desktop Client

This MCP server is designed to work with Claude Desktop Client. You can set it up easily with the following steps:

1. Build the server:

   go build -o osmmcp ./cmd/osmmcp
   

2. Generate or update the Claude Desktop Client configuration:

   ./osmmcp --generate-config ~/Library/Application\ Support/Anthropic/Claude/config.json
   

   This will add an OSM entry to the mcpServers configuration in Claude Desktop Client. The configuration system intelligently:

   • Creates the file if it doesn't exist
   • Preserves existing tools when updating the configuration
   • Uses absolute paths to ensure Claude can find the executable
   • Validates JSON output to prevent corruption

3. Restart Claude Desktop Client to load the updated configuration.

4. In a conversation with Claude, you can now use the OpenStreetMap MCP tools.

The configuration file will look similar to this:

{
  "mcpServers": {
    "OSM": {
      "command": "/path/to/osmmcp",
      "args": []
    },
  }
}

API Dependencies

The server relies on these external APIs:

• Nominatim - For geocoding operations
• Overpass API - For OpenStreetMap data queries
• OSRM - For routing calculations

No API keys are required as these are open public APIs, but the server follows usage policies including proper user agent identification and request rate limiting.

Development

Project Structure

• cmd/osmmcp - Main application entry point
• pkg/server - MCP server implementation
• pkg/tools - OpenStreetMap tool implementations and tool registry
• pkg/osm - Common OpenStreetMap utilities and helpers
• pkg/geo - Geographic types and calculations
• pkg/cache - Caching layer for API responses

Adding New Tools

To add a new tool:

1. Implement the tool functions in a new or existing file in pkg/tools
2. Add the tool definition to the registry in pkg/tools/registry.go

The registry-based design makes it easy to add new tools without modifying multiple files. All tool definitions are centralized in one place, making the codebase more maintainable.

Troubleshooting

If you encounter build errors about redeclared types or functions, you might have older files from previous implementations. Check for and remove any conflicting files:

# Check for specialized.go which might conflict with newer implementations
rm -f pkg/tools/specialized.go pkg/tools/specialized_*.go

# Check for mock.go which might contain test implementations
rm -f pkg/tools/mock.go

Acknowledgments

This implementation is based on two excellent sources:

• jagan-shanmugam/open-streetmap-mcp - The original Python implementation
• MCPLink OSM MCP Server - The MCPLink version with additional features

Project History

Originally created by @pdfinn.
All core functionality and initial versions developed prior to organisational transfer.

License

MIT License