{
  "markdown": "# overspan-mcp\n\nAn MCP (Model Context Protocol) server for [Overspan](https://overspan.dev), the hosted Overpass API. It gives Claude, Cursor, and any other MCP client direct, metered access to full-planet OpenStreetMap data: raw Overpass QL plus helper tools for nearby search, bounding-box search, counting, and usage checks.\n\nYou need an Overspan API key. Plans start at $19/month at [overspan.dev](https://overspan.dev/#pricing); the key arrives by email after checkout, no account needed.\n\n## Quickstart\n\n### Claude Code\n\n```bash\nclaude mcp add overspan --env OVERSPAN_API_KEY=YOUR_KEY -- npx -y overspan-mcp\n```\n\n### Claude Desktop, Cursor, and other JSON-configured clients\n\n```json\n{\n  \"mcpServers\": {\n    \"overspan\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"overspan-mcp\"],\n      \"env\": {\n        \"OVERSPAN_API_KEY\": \"YOUR_KEY\"\n      }\n    }\n  }\n}\n```\n\nThe key must be in the server's `env` block. MCP clients start servers with their own environment, so a variable exported in your shell profile will not reach it. Treat any config file containing the key as a secret; in Claude Code's `.mcp.json` you can write `\"OVERSPAN_API_KEY\": \"${OVERSPAN_KEY}\"` to keep the key in your environment and out of the file.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `overpass_query` | Run a raw Overpass QL query. The escape hatch when the helpers are too narrow. |\n| `find_nearby` | Features matching tag filters within a radius of a point. |\n| `features_in_bbox` | Features matching tag filters inside a bounding box. |\n| `count_features` | Count matches in an area without returning them. Cheap; use it before pulling data. |\n| `get_usage` | The key's tier, limits, month-to-date quota, and recent requests. Never consumes quota. |\n\nThe server also exposes two resources the model can read (`overspan://overpass-ql`, a QL cheat sheet, and `overspan://differences`, how Overspan differs from the public servers) and one prompt (`write-bounded-overpass-query`).\n\n## Behaviour worth knowing\n\n- The key is sent as an `Authorization: Bearer` header, never in a URL.\n- Every successful tool result carries a quota line (`[quota] 49998 of 50000 monthly requests remaining`) so an agent can pace itself. `get_usage` gives the full picture and is free to call.\n- Errors come back in plain language with the gateway's error code, what it means, and whether to retry. Rejected requests do not consume quota, and a runaway loop is bounded by the key's own rate and concurrency caps, never by a larger bill.\n- Oversized responses are trimmed to fit a model's context: for Overpass JSON the element list is cut and the result says how many elements were dropped. Raise the cap with `OVERSPAN_MAX_RESPONSE_CHARS` if you want more.\n- Queries without `[timeout:]` get 25 seconds. Set it explicitly for heavy queries, up to your tier's cap.\n\n## Environment variables\n\n| Variable | Required | Default | Purpose |\n|---|---|---|---|\n| `OVERSPAN_API_KEY` | yes | | Your Overspan API key |\n| `OVERSPAN_API_URL` | no | `https://api.overspan.dev` | Override the API endpoint |\n| `OVERSPAN_MAX_RESPONSE_CHARS` | no | `48000` | Truncation threshold for tool results |\n\n## Data licence\n\nResults are OpenStreetMap data, licensed under the [Open Database License](https://opendatacommons.org/licenses/odbl/). Anything you publish that shows or derives from this data needs a visible credit reaching [openstreetmap.org/copyright](https://www.openstreetmap.org/copyright). Your Overspan subscription pays for hosting and access, not for the data, and does not change those obligations.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nThe test suite covers the query builders, response shaping, error mapping, and a full in-memory MCP client round trip.\n\n## Links\n\n- [Overspan documentation](https://overspan.dev/docs/)\n- [Error reference](https://overspan.dev/docs/errors)\n- [Usage dashboard](https://overspan.dev/usage)\n\nOverspan is an independent service, not affiliated with the OpenStreetMap Foundation or the Overpass API project.\n\nMIT licensed.\n",
  "bytes": 4046,
  "sha": "85f8d01cd19dfecb0794be85a73099cf7aabbf1565ae7908f6cb088fdf29be11",
  "repo_slug": "julesmaxxx/overspan-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_overspan_mcp_fce7d639/readme"
}