geocode-mcp

Geocoding MCP Server 🗺️

Turn place names and addresses into coordinates (and back) for Claude Desktop and any MCP-compatible client, powered by OpenStreetMap Nominatim. Forward & reverse geocoding, place/POI search, and distance between locations — all from natural language. No API key required.

npm package: geocode-mcp  ·  GitHub repo: danishashko/geocode-mcp.

🎯 What You Get

• 📍 Geocode — address/place/landmark → latitude & longitude
• 🔄 Reverse geocode — coordinates → human-readable address
• 🔎 Place search — find POIs/places by description
• 📏 Distance — straight-line distance between two named places

Geocoding is something LLMs can't reliably do on their own — this gives Claude real, current coordinates from OpenStreetMap. Every tool returns human-readable markdown by default, or structured JSON on request (response_format: "json"). Lightweight (Python standard library + mcp only), no API key.

🚀 Quick Start

Add this to your Claude Desktop config and restart Claude:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geocode": {
      "command": "npx",
      "args": ["-y", "geocode-mcp"],
      "env": {
        "GEOCODE_USER_AGENT": "your-app-name [e-mail]"
      }
    }
  }
}

OpenStreetMap asks every client to send a descriptive User-Agent with contact info. Set GEOCODE_USER_AGENT to your own name/email (a default is provided so it works out of the box). On first launch the npx wrapper creates an isolated Python environment and installs the dependency (one-time, ~a minute). You need Python 3.10+ and Node.js 16+.

Prefer a global install?

npm install -g geocode-mcp

{
  "mcpServers": {
    "geocode": {
      "command": "geocode-mcp",
      "env": { "GEOCODE_USER_AGENT": "your-app-name [e-mail]" }
    }
  }
}

🔧 Available Tools

Tool	What it returns	Parameters
geocode	Ranked coordinate matches for an address/place/landmark	query, limit, country_codes
reverse_geocode	The address at a given latitude/longitude	latitude, longitude
search_places	Places/POIs matching a description, with coordinates	query, limit, country_codes
distance_between	Straight-line distance between two named places	origin, destination, unit

Every tool also accepts response_format ("markdown", the default, or "json"). country_codes is an optional comma-separated ISO 3166-1 alpha-2 filter (e.g. us or us,ca).

💬 Example Prompts

Once the server is connected, just ask Claude:

• "What are the coordinates of the Eiffel Tower?"
• "What's at latitude 40.7484, longitude -73.9857?"
• "Find bookstores in Paris."
• "How far is it from London to Edinburgh in miles?"
• "Geocode '1600 Pennsylvania Avenue' — US only."

🐛 Troubleshooting

"OpenStreetMap is rate-limiting requests" Nominatim's public server allows ~1 request/second. This server self-throttles, but if you still hit it, wait a moment.

"No locations found" Try a more specific or differently-worded query, or add a country_codes filter to disambiguate.

"Command not found" / "Python not found" Ensure Python 3.10+ and Node.js 16+ are installed and on your PATH. On macOS/Linux, try python3.

Tools not showing up in Claude

• Confirm the config file is valid JSON (no trailing commas).
• Fully quit and reopen Claude Desktop.

🛠️ Manual Installation (Alternative)

If you would rather run the Python file directly instead of via npx:

1. Download the server and install the dependency

pip install mcp

(or pip3 on macOS/Linux)

2. Point Claude Desktop at it

{
  "mcpServers": {
    "geocode": {
      "command": "python3",
      "args": ["/absolute/path/to/geocode_mcp.py"],
      "env": { "GEOCODE_USER_AGENT": "your-app-name [e-mail]" }
    }
  }
}

On Windows use "command": "python" and a path like "C:\\path\\to\\geocode_mcp.py".

3. Restart Claude Desktop.

🔒 Privacy & Usage Policy

• Uses OpenStreetMap's free Nominatim API — public, no key.
• Requests go straight from your machine to OpenStreetMap. Nothing is stored or proxied.
• Per the Nominatim Usage Policy, the server sends a descriptive User-Agent and self-throttles to ~1 request/second. Please don't use it for bulk/heavy workloads against the public server.
• Data © OpenStreetMap contributors, available under the ODbL.

📝 Notes

• distance_between returns straight-line (great-circle) distance, not driving/route distance.
• Results are ranked by relevance/importance; use country_codes to narrow ambiguous names (e.g. "Springfield").
• Reverse geocoding near water or remote areas may return no address.

📋 Changelog

See CHANGELOG.md for the full version history.

📚 Resources

• Model Context Protocol
• Nominatim API documentation
• Nominatim Usage Policy

⚖️ Legal Disclaimer

This tool uses the OpenStreetMap Nominatim API but is not affiliated with or endorsed by the OpenStreetMap Foundation. Geocoding data © OpenStreetMap contributors, licensed under the Open Database License. Use is subject to the Nominatim Usage Policy.

👤 Author

Daniel Shashko

• GitHub: @danishashko
• LinkedIn: daniel-shashko
• npm: danielshashko

📄 License

MIT © Daniel Shashko