Skip to main content

Geo MCP

Geo MCP gives coding agents two read-only geocoding tools backed by Photon and OpenStreetMap:

  • search_places finds addresses, settlements, streets, and named features.
  • reverse_geocode finds the nearest place for a latitude and longitude.

The hosted Streamable HTTP endpoint is:

https://app.chibigeo.com/mcp

It uses your existing ChibiGeo account, plan, quota, and ck_… API key. Tool discovery is public; a lookup requires the key and consumes one normal ChibiGeo request. Geo MCP does not provide routing, POI discovery, maps, batch requests, or an embedded LLM.

Create a suitable key​

Create a dedicated key in the ChibiGeo dashboard. A server-side MCP client normally sends no browser Origin, so do not add an Origin allowlist to this key. Fixed-IP allowlists are suitable only when the MCP client has a stable, known outbound IP.

Put the key in your environment instead of committing it:

export CHIBIGEO_API_KEY='ck_your_key_here'

Codex​

Current Codex releases can read a bearer token from an environment variable:

codex mcp add chibigeo \
  --url https://app.chibigeo.com/mcp \
  --bearer-token-env-var CHIBIGEO_API_KEY

Verify with codex mcp get chibigeo.

Claude Code​

Add this project-level .mcp.json (or use the equivalent user-level config):

{
  "mcpServers": {
    "chibigeo": {
      "type": "http",
      "url": "https://app.chibigeo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CHIBIGEO_API_KEY}"
      }
    }
  }
}

Claude Code expands the environment variable when it reads the configuration. Use /mcp or claude mcp get chibigeo to verify the connection.

Cursor​

Add this to .cursor/mcp.json for one project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "chibigeo": {
      "url": "https://app.chibigeo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CHIBIGEO_API_KEY}"
      }
    }
  }
}

Cursor resolves ${env:CHIBIGEO_API_KEY} from the environment. Enable the server under Customize → MCP and inspect MCP Logs if it does not connect.

Tool contracts​

search_places​

query is required and limited to 256 characters. Optional inputs are language, limit (1–10, default 5), focus, bounding_box, one country_code, and one Photon place_type (house, street, locality, district, city, county, state, country, or other).

The result contains places in Photon rank order. Each Place uses named latitude/longitude and optional label, address, bounds, kind, and OSM source fields. No match is a successful result with places: [].

reverse_geocode​

latitude and longitude are required. Optional inputs are language and radius_km from 0 to 100. It requests one result. No match is a successful result with place: null.

Both results include © OpenStreetMap contributors and the OpenStreetMap copyright URL. Geo MCP never returns raw Photon GeoJSON, arbitrary extra fields, or an invented confidence score.

Errors and privacy​

Expected failures are returned with stable codes such as missing_api_key, invalid_api_key, key_restricted, rate_limited, quota_exceeded, subscription_past_due, upstream_timeout, and upstream_unavailable. Account and quota details remain in the ChibiGeo dashboard.

Search text, coordinates, and geocoding results are processed transiently and are not stored or logged. The adapter does not cache or retry lookups. API keys must be sent only in Authorization: Bearer … or X-Api-Key; URL credentials are not accepted by Geo MCP.

Geo MCP supports MCP revisions 2026-07-28 and 2025-11-25. OAuth and official ChatGPT custom-app support are not part of this beta.