{
  "markdown": "# Geocoding MCP Server 🗺️\n\n[![npm version](https://img.shields.io/npm/v/geocode-mcp.svg)](https://www.npmjs.com/package/geocode-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/geocode-mcp.svg)](https://www.npmjs.com/package/geocode-mcp)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nTurn 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.**\n\n> **npm package:** [`geocode-mcp`](https://www.npmjs.com/package/geocode-mcp)  ·  **GitHub repo:** [`danishashko/geocode-mcp`](https://github.com/danishashko/geocode-mcp).\n\n## 🎯 What You Get\n\n- 📍 **Geocode** — address/place/landmark → latitude & longitude\n- 🔄 **Reverse geocode** — coordinates → human-readable address\n- 🔎 **Place search** — find POIs/places by description\n- 📏 **Distance** — straight-line distance between two named places\n\nGeocoding 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.\n\n## 🚀 Quick Start\n\nAdd this to your Claude Desktop config and restart Claude:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"geocode\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"geocode-mcp\"],\n      \"env\": {\n        \"GEOCODE_USER_AGENT\": \"your-app-name your@email.com\"\n      }\n    }\n  }\n}\n```\n\nOpenStreetMap 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+**.\n\n### Prefer a global install?\n\n```bash\nnpm install -g geocode-mcp\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"geocode\": {\n      \"command\": \"geocode-mcp\",\n      \"env\": { \"GEOCODE_USER_AGENT\": \"your-app-name your@email.com\" }\n    }\n  }\n}\n```\n\n## 🔧 Available Tools\n\n| Tool | What it returns | Parameters |\n|------|-----------------|------------|\n| `geocode` | Ranked coordinate matches for an address/place/landmark | `query`, `limit`, `country_codes` |\n| `reverse_geocode` | The address at a given latitude/longitude | `latitude`, `longitude` |\n| `search_places` | Places/POIs matching a description, with coordinates | `query`, `limit`, `country_codes` |\n| `distance_between` | Straight-line distance between two named places | `origin`, `destination`, `unit` |\n\nEvery 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`).\n\n## 💬 Example Prompts\n\nOnce the server is connected, just ask Claude:\n\n- \"What are the coordinates of the Eiffel Tower?\"\n- \"What's at latitude 40.7484, longitude -73.9857?\"\n- \"Find bookstores in Paris.\"\n- \"How far is it from London to Edinburgh in miles?\"\n- \"Geocode '1600 Pennsylvania Avenue' — US only.\"\n\n## 🐛 Troubleshooting\n\n**\"OpenStreetMap is rate-limiting requests\"**\nNominatim's public server allows ~1 request/second. This server self-throttles, but if you still hit it, wait a moment.\n\n**\"No locations found\"**\nTry a more specific or differently-worded query, or add a `country_codes` filter to disambiguate.\n\n**\"Command not found\" / \"Python not found\"**\nEnsure Python 3.10+ and Node.js 16+ are installed and on your PATH. On macOS/Linux, try `python3`.\n\n**Tools not showing up in Claude**\n1. Confirm the config file is valid JSON (no trailing commas).\n2. Fully quit and reopen Claude Desktop.\n\n**Using a different model or provider (LiteLLM, OpenRouter, NVIDIA NIM, a local model)**\nThis server never talks to a model. Your client starts it as a local process and\nspeaks JSON-RPC over stdin/stdout, so changing `ANTHROPIC_BASE_URL` or swapping the\nmodel behind your client has no effect on it. If tools stop firing after a switch\nlike that, check two things: the model has to support function calling, and a proxy\nconfigured to drop unsupported parameters can silently strip your tool definitions,\nwhich produces no error at all. Run `/mcp` in your client (or `claude mcp list`) to\nconfirm the server is connected before suspecting the server.\n\n## 🛠️ Manual Installation (Alternative)\n\nIf you would rather run the Python file directly instead of via npx:\n\n**1. Download the server and install the dependency**\n\n```bash\npip install mcp\n```\n\n(or `pip3` on macOS/Linux)\n\n**2. Point Claude Desktop at it**\n\n```json\n{\n  \"mcpServers\": {\n    \"geocode\": {\n      \"command\": \"python3\",\n      \"args\": [\"/absolute/path/to/geocode_mcp.py\"],\n      \"env\": { \"GEOCODE_USER_AGENT\": \"your-app-name your@email.com\" }\n    }\n  }\n}\n```\n\nOn Windows use `\"command\": \"python\"` and a path like `\"C:\\\\path\\\\to\\\\geocode_mcp.py\"`.\n\n**3. Restart Claude Desktop.**\n\n## 🔒 Privacy & Usage Policy\n\n- Uses OpenStreetMap's free [Nominatim API](https://nominatim.org) — public, no key.\n- Requests go straight from your machine to OpenStreetMap. Nothing is stored or proxied.\n- 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.\n- Data © OpenStreetMap contributors, available under the [ODbL](https://www.openstreetmap.org/copyright).\n\n## 📝 Notes\n\n- `distance_between` returns straight-line (great-circle) distance, **not** driving/route distance.\n- Results are ranked by relevance/importance; use `country_codes` to narrow ambiguous names (e.g. \"Springfield\").\n- Reverse geocoding near water or remote areas may return no address.\n\n## 📋 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n## 📚 Resources\n\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Nominatim API documentation](https://nominatim.org/release-docs/latest/api/Overview/)\n- [Nominatim Usage Policy](https://operations.osmfoundation.org/policies/nominatim/)\n\n## ⚖️ Legal Disclaimer\n\nThis 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/).\n\n## 👤 Author\n\n**Daniel Shashko**\n- GitHub: [@danishashko](https://github.com/danishashko)\n- LinkedIn: [daniel-shashko](https://linkedin.com/in/daniel-shashko)\n- npm: [danielshashko](https://www.npmjs.com/~danielshashko)\n\n## 📄 License\n\nMIT © Daniel Shashko\n",
  "bytes": 7223,
  "sha": "f1a6b927cd5afc05a1d1b255a2e262b66ba88788b2f7cb5ab6521fe83d151938",
  "repo_slug": "danishashko/geocode-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_danishashko_geocode_mcp_191b4299/readme"
}