# overpass-mcp

An [MCP](https://modelcontextprotocol.io) server that lets an agent run
[Overpass QL](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL)
queries against the OpenStreetMap Overpass API.

## Install

```sh
npm install
```

## Run

```sh
npm start
```

It speaks MCP over stdio.

## Configure (opencode)

```json
{
  "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.

| argument | required | description |
| --- | --- | --- |
| `query` | yes | Overpass QL, e.g. `[out:json][timeout:25];node[amenity=cafe](around:300,51.5074,-0.1278);out;` |
| `endpoint` | no | Overpass API endpoint (default `https://overpass-api.de/api/interpreter`) |
| `timeout_ms` | no | request timeout in ms (default 60000) |

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

## Test

```sh
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](https://www.openstreetmap.org/copyright) 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](LICENSE). Use, modify, and distribute freely; keep the copyright and
license notice.