Overpass API in Claude, ChatGPT and Cursor (MCP)

overpass.ch is an MCP server (Model Context Protocol). An AI assistant connected to it runs Overpass queries on the full OpenStreetMap planet, finds places and looks up heights by itself, and answers from the current data.

https://api.overpass.ch/v1/YOUR_API_KEY/mcp

Setup

Create a separate key for each assistant on the API keys page, named after it, and leave its allowed referers empty. You can then revoke it on its own.

Claude (web, desktop and mobile apps)

1. Open Customize → Connectors, click + Add and Add custom connector.
2. Name: overpass.ch. URL: the URL above with your key.
3. Authentication: No sign in. Click Add.

Free accounts of Claude can add one custom connector. The calls come from the servers of Anthropic, so the connector works the same in the desktop and mobile apps. In a Team or Enterprise organisation, an owner adds the connector, and everyone who uses it shares the key.

ChatGPT

1. Open chatgpt.com/plugins, select + and Add custom MCP server.
2. Enter a name and description, and under Connection the URL above with your key.
3. Choose no authentication, confirm the warning and select Create as a plugin.

ChatGPT then shows the tools it found. Your ChatGPT plan or workspace has to allow custom MCP servers. ChatGPT asks before tools that change something; the tools of overpass.ch only read data.

Claude Code

claude mcp add --transport http overpass https://api.overpass.ch/v1/mcp \
  --header "X-API-Key: YOUR_API_KEY"

In Claude Code, the tools are called mcp__overpass__overpass_query and so on.

Cursor

In ~/.cursor/mcp.json, with the key in the environment variable OVERPASS_KEY:

{
  "mcpServers": {
    "overpass": {
      "url": "https://api.overpass.ch/v1/mcp",
      "headers": { "X-API-Key": "${env:OVERPASS_KEY}" }
    }
  }
}

VS Code

In .vscode/mcp.json. VS Code asks for the key the first time and stores it:

{
  "inputs": [
    { "type": "promptString", "id": "overpass-key", "description": "overpass.ch API key", "password": true }
  ],
  "servers": {
    "overpass": {
      "type": "http",
      "url": "https://api.overpass.ch/v1/mcp",
      "headers": { "X-API-Key": "${input:overpass-key}" }
    }
  }
}

Other clients that speak MCP over Streamable HTTP work the same way. The server speaks protocol version 2026-07-28 and the versions from 2025-03-26 to 2025-11-25.

What to ask

Ask in plain language. The assistant picks the tools; these are the calls that three questions led to.

“How many pharmacies in Zürich are within 200 m of a tram stop?”

1. geocode with Zürich and kind city returns the city, relation 1682248, with overpass_area_id 3601682248.
2. overpass_query counts:

   [out:json][timeout:25];
   area(id:3601682248)->.a;
   node["railway"="tram_stop"](area.a)->.stops;
   nwr["amenity"="pharmacy"](around.stops:200)(area.a);
   out count;

The answer on 4 November 2026: 87 of the 103 pharmacies in the city. Two calls: one geocoding request and one Overpass request.

“Which mountain huts in Valais lie above 2,500 m?”

geocode finds the canton (overpass_area_id 3601686699), and overpass_query lists its 124 huts with add_elevation, which adds the height of each point from the 2 m grid of swisstopo. The assistant then sorts and filters the list.

“How many cafés did Lausanne have in 2015, and how many today?”

Two queries of the same area, one with [date:"2015-01-01T00:00:00Z"] in the settings line. History queries need the Medium or Large plan; on the other plans the tool answers that, with a link to the prices.

When the right query is not obvious, the assistant can call overpass_examples, which searches the query examples by topic.

The tools

Assistants read text, so overpass_query answers with a first line that counts the elements by type and gives the data timestamp, then the ODbL notice, then one element per line as compact JSON. An answer over 30,000 characters is cut; the first line then says how many elements there were, and the assistant can ask for the next part with offset, raise max_chars up to 200,000, or narrow the query. Every call counts, a cut one too, so out count; and out center 50; save requests.

Limits and errors

• Tool calls count against the limits of your plan like the same calls of the REST API. Listing the tools is free and works without a key.
• Overpass queries through MCP stop after 120 s at most, and after 25 s when the query does not set [timeout:]. The REST API allows the plan maximum.
• The free plan runs one Overpass query at a time and 30 requests a minute. An assistant that sends two queries at once gets a refusal for the second one.
• A refusal reaches the assistant as text: the message of the API, what to do, and the seconds to wait. The assistant is told to pass it on and not to retry in a loop.
• A missing or revoked key gives the error unauthorized on the first tool call, with the address of the API keys page. A key of the type “Maps only” works for geocoding, not for Overpass and elevation.

Keys and data

The key in the URL ends up in the settings of the assistant, and in a shared workspace everyone with the connector uses it. Revoke it on the API keys page when you remove the connector; a revoked key stops working at once. overpass.ch logs tool calls like API requests: the key id, never the key, and queries only as a hash. Tag values in the answers are text written by OpenStreetMap contributors, and the assistant is told to treat them as data.

MCP servers that use overpass-api.de

An MCP server that sends its queries to the public server overpass-api.de falls under the rules of that server. For anything that runs regularly, its policy in the OpenStreetMap wiki allows about 100 queries a day, it answers scripts without their own User-Agent with 406, and it bans addresses after repeated 429 errors. An assistant that retries in a loop runs into those limits. The alternatives guide compares the options.