# Opencages [Health: Active]

**Category:** 🗺️ Location Services  
**Repository:** https://github.com/pipeworx-io/mcp-opencages  
**GitHub Stars:** 0  
**npm Downloads (last month):** 446  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/opencages

## Description
OpenCage forward + reverse geocoding (free key, 2500/day)

## Tools
Capabilities this server exposes over MCP:

- **geocode** — Forward-geocode an address or place name to latitude/longitude using OpenCage (requires API key); supports country-code filtering, bounding box, and language; returns coordinates and structured address components.
- **reverse** — Reverse-geocode a latitude/longitude pair to a human-readable address using OpenCage (requires API key); returns formatted address, country, city, postcode, and timezone.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `PLATFORM_OPENCAGE_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

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

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

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

_Full upstream README: https://allmcps.com/mcp/opencages/readme_