# Geocoding MCP Server 🗺️

[![npm version](https://img.shields.io/npm/v/geocode-mcp.svg)](https://www.npmjs.com/package/geocode-mcp)
[![npm downloads](https://img.shields.io/npm/dm/geocode-mcp.svg)](https://www.npmjs.com/package/geocode-mcp)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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

> **npm package:** [`geocode-mcp`](https://www.npmjs.com/package/geocode-mcp)  ·  **GitHub repo:** [`danishashko/geocode-mcp`](https://github.com/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`

```json
{
  "mcpServers": {
    "geocode": {
      "command": "npx",
      "args": ["-y", "geocode-mcp"],
      "env": {
        "GEOCODE_USER_AGENT": "your-app-name your@email.com"
      }
    }
  }
}
```

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?

```bash
npm install -g geocode-mcp
```

```json
{
  "mcpServers": {
    "geocode": {
      "command": "geocode-mcp",
      "env": { "GEOCODE_USER_AGENT": "your-app-name your@email.com" }
    }
  }
}
```

## 🔧 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**
1. Confirm the config file is valid JSON (no trailing commas).
2. Fully quit and reopen Claude Desktop.

**Using a different model or provider (LiteLLM, OpenRouter, NVIDIA NIM, a local model)**
This server never talks to a model. Your client starts it as a local process and
speaks JSON-RPC over stdin/stdout, so changing `ANTHROPIC_BASE_URL` or swapping the
model behind your client has no effect on it. If tools stop firing after a switch
like that, check two things: the model has to support function calling, and a proxy
configured to drop unsupported parameters can silently strip your tool definitions,
which produces no error at all. Run `/mcp` in your client (or `claude mcp list`) to
confirm the server is connected before suspecting the server.

## 🛠️ Manual Installation (Alternative)

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

**1. Download the server and install the dependency**

```bash
pip install mcp
```

(or `pip3` on macOS/Linux)

**2. Point Claude Desktop at it**

```json
{
  "mcpServers": {
    "geocode": {
      "command": "python3",
      "args": ["/absolute/path/to/geocode_mcp.py"],
      "env": { "GEOCODE_USER_AGENT": "your-app-name your@email.com" }
    }
  }
}
```

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](https://nominatim.org) — public, no key.
- Requests go straight from your machine to OpenStreetMap. Nothing is stored or proxied.
- Per the [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/), 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](https://www.openstreetmap.org/copyright).

## 📝 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](CHANGELOG.md) for the full version history.

## 📚 Resources

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Nominatim API documentation](https://nominatim.org/release-docs/latest/api/Overview/)
- [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/)

## ⚖️ 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](https://www.openstreetmap.org/copyright). Use is subject to the [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/).

## 👤 Author

**Daniel Shashko**
- GitHub: [@danishashko](https://github.com/danishashko)
- LinkedIn: [daniel-shashko](https://linkedin.com/in/daniel-shashko)
- npm: [danielshashko](https://www.npmjs.com/~danielshashko)

## 📄 License

MIT © Daniel Shashko