overpass-mcp

An MCP server that lets an agent run Overpass QL queries against the OpenStreetMap Overpass API.

Install

npm install

Related MCP server: mcp-overpass

Run

npm start

It speaks MCP over stdio.

Configure (opencode)

{
  "mcp": {
    "overpass": {
      "type": "local",
      "command": ["node", "/absolute/path/to/overpass-mcp/index.js"]
    }
  }
}

Tool: overpass_query

Runs an Overpass QL query and returns the raw response.

Responses are truncated at 200 kB to protect the model's context; narrow the query if you see a truncation notice.

Test

npm test            # offline unit tests (retry + truncation), CI-safe
npm run test:live   # one live query against a public endpoint

test never touches the network. test:live does, and can fail when a public instance is busy.

Notes

• A User-Agent header is sent because the public Overpass endpoint rejects requests from unknown clients (notably Node's default undici UA) with HTTP 406.

• The public instances intermittently shed load with HTTP 429/503/504. The client retries those twice with a short backoff before giving up.

• Public Overpass instances are rate limited. For heavy use, point endpoint at your own instance.

Disclaimer

The default endpoints are free, community-run public services. They are not yours and they are not guaranteed.

• Respect the servers. Space out queries, cache results, and avoid heavy or automated bulk querying. Do not hammer the endpoint.

• Allow time. Queries may be slow, rate limited, or intermittently return HTTP 429/503/504. The client retries a little, but patience is expected.

• Follow the rules. You are responsible for complying with the usage policies and terms of whichever endpoint you use, and with the OpenStreetMap licence (data © OpenStreetMap contributors, ODbL).

• No warranty, no liability. This software is provided "as is", without warranty of any kind. The author is not responsible for any use, misuse, rate limiting, blocks, data loss, or damages arising from it.

If you need volume or reliability, run your own Overpass instance and point endpoint at it.

License

MIT. Use, modify, and distribute freely; keep the copyright and license notice.