Opencages

What Opencages MCP server does

The Opencages MCP server provides two location lookup operations backed by OpenCage's geocoding endpoint. Forward geocoding accepts a text query such as an address, city, or place name and returns matching geographic results. Reverse geocoding accepts latitude and longitude and resolves them into location data.

OpenCage aggregates information from sources including OpenStreetMap, GeoNames, and Who's On First. The service offers a free tier with a stated allowance of 2,500 requests per day, and an API key is required.

How it works

The geocode tool accepts a query and optional controls for language, maximum result count, country-code filtering, a geographic bounding box, annotations, and abbreviated output. The reverse tool accepts coordinates and optional language, annotation, and abbreviation settings.

Requests use OpenCage's JSON geocoding API. An agent can invoke the tools through MCP, ask the Pipeworx gateway to select and populate a tool using ask_pipeworx, or call a gateway HTTP tool endpoint directly. The gateway route serves the Opencages tools alongside shared Pipeworx meta-tools, whereas the local process exposes only the two location tools.

Setup and configuration

For a hosted connection, add the Pipeworx MCP URL to an MCP client:

{
  "mcpServers": {
    "opencages": {
      "url": "https://gateway.pipeworx.io/opencages/mcp"
    }
  }
}

A local installation can run without a Pipeworx account or gateway round trip:

{
  "mcpServers": {
    "opencages": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-opencages"]
    }
  }
}

The package communicates over stdin and stdout. Hosted authentication uses PLATFORM_OPENCAGE_KEY; bring-your-own-key requests can supply an API key with the ?_apiKey=... parameter.

Tools and capabilities

• geocode: searches for locations from a text query.
• reverse: looks up a location from latitude and longitude.
• Language options: request results in a selected language.
• Result controls: limit forward results, restrict by country code, or provide bounds.
• Output controls: disable annotations or request abbreviated results where supported.
• ask_pipeworx: on gateway connections, submit a natural-language request for tool selection and argument filling.

Limitations and notes

The service depends on an OpenCage API key and its service limits. The free allowance is listed as 2,500 requests per day; applications with higher volume should account for OpenCage's applicable limits.

A gateway connection lists the pack's tools plus roughly 30 shared Pipeworx tools, so its tool count is larger than the two operations described here. The gateway's initialize response is the authoritative source for the tools available at a given time. If extra schemas are undesirable, the local stdio mode exposes only the Opencages tools, but it does not provide gateway-wide routing through ask_pipeworx.

The hosted pack URL and the full Pipeworx gateway use the same gateway and data sources. They differ in which pack tools are listed directly. HTTP users can invoke opencages_geocode through the gateway without an MCP client.