OpenCage Geocoding

Provides forward and reverse geocoding using OpenCage, plus API usage status for MCP clients.

javascript

17

GitHub Stars

javascript

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "opencagedata-opencage-geocoding-mcp": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/opencage-geocoding-mcp/build/index.js"
      ],
      "env": {
        "OPENCAGE_API_KEY": "your_opencage_geocoding_api_key_here"
      }
    }
  }
}

You can run a geocoding MCP server powered by the OpenCage API to convert between addresses and geographic coordinates. This server exposes forward and reverse geocoding capabilities and lets you monitor API usage from compliant MCP clients, enabling you to integrate reliable location data into your workflows.

How to use

Use a compatible MCP client to connect to the server. The OpenCage MCP server accepts two main geocoding directions: forward geocoding, which converts addresses or place names into coordinates, and reverse geocoding, which retrieves addresses from coordinates. You can also query the server for current API usage and rate limits if your account supports it.

To perform geocoding tasks, provide your queries through the MCP client’s geocode-forward or geocode-reverse endpoints. Forward geocoding takes a query string and optional constraints such as country codes, bounding boxes, target language, result limits, and whether to exclude annotations. Reverse geocoding requires latitude and longitude values along with optional language and annotation options. The server returns coordinates, addresses, and contextual details suitable for display and downstream processing.

For operational status, you can request current API usage and rate limits through the get-opencage-info capability, which reports remaining requests and reset times when supported by your subscription.

How to install

Prerequisites you need before starting are: Node.js version 20 or higher and an OpenCage geocoding API key.

Clone the repository and enter the project folder.

git clone https://github.com/OpenCageData/opencage-geocoding-mcp.git
cd opencage-geocoding-mcp

Install dependencies.

npm install

Set your API key as an environment variable so the MCP can access the OpenCage service.

export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"

Build the project to generate the MCP runtime files.

npm run build

Run the MCP server from your local environment

The project provides a local runtime that can be launched as a standard MCP server. The runtime is executed via Node.js and points to the built index.

Use the following runtime command to start the MCP server after building, assuming you keep the default build output path.

node /ABSOLUTE/PATH/TO/opencage-geocoding-mcp/build/index.js

Available tools

geocode-forward

Converts an address or place name into geographic coordinates, with optional constraints for country, bounds, language, limit, and annotation control.

geocode-reverse

Converts latitude and longitude into a human-readable address, with optional language and annotation options.

get-opencage-info

Returns information about remaining requests, rate limits, and reset times when available.