Geocoding
Forward and reverse geocoding, place search, and distance via OpenStreetMap Nominatim. No key.
Open source Open in the app JSON README (API)
About
Forward and reverse geocoding, place search, and distance via OpenStreetMap Nominatim. No key.
Details
- Kind
- MCP servers
- Topic
- Maps, weather & travel
- Publisher
- danishashko
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.2
- Stars
- 1
- Last push
- 2026-08-06T15:46:15Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.danishashko/geocode-mcp
README
# Geocoding MCP Server 🗺️
[](https://www.npmjs.com/package/geocode-mcp)
[](https://www.npmjs.com/package/geocode-mcp)
[](https://www.python.org/downloads/)
[](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