OpenCage Geocoding MCP Server

An MCP (Model Context Protocol) server that provides geocoding capabilities using the OpenCage geocoding API. This server allows you to convert between addresses and geographic coordinates.

PLEASE NOTE: the examples shown here are based on an integration with claude.ai's desktop client. MCP as a concept is supported by other services, but may require a slightly different configuration.

Features

• Forward Geocoding: Convert addresses or place names to coordinates (latitude/longitude)
• Reverse Geocoding: Convert coordinates to addresses
• API Status Monitoring: Check your API usage and rate limits (assuming your penCage account has hard limits).

Prerequisites

1. Node.js (version 20 or higher)
2. OpenCage geocoding API Key: Sign up on the OpenCage website to get a free-trial geocoding API key

Installation

1. Clone the repository. Change into the repository directory

git clone git@github.com:OpenCageData/opencage-geocoding-mcp.git
# or
git clone https://github.com/OpenCageData/opencage-geocoding-mcp.git

cd opencage-geocoding-mcp

2. Install dependencies:

npm install

3. Set your OpenCage geocoding API key as an environment variable:

export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"

4. Build the project:

npm run build

Usage

Using within Claude Desktop

Add this configuration to your Claude Desktop config file

On a Mac the config file should be (~/Library/Application Support/Claude/claude_desktop_config.json), but you can also navigate to the file via the menu: Settings > Developer > Edit Config

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

Available Tools

Note: the first time you run a command you will need to give Claude permission

1. geocode-forward

Convert an address or place name to coordinates and information about that location.

Parameters:

• query (required): The address or place name to geocode
• countrycode (optional): Restrict to country (ISO 3166-1 alpha-2 code)
• bounds (optional): Bounding box (min_lon,min_lat,max_lon,max_lat)
• language (optional): Language for results (e.g., 'en', 'de', 'fr')
• limit (optional): Max results (1-100, default 10)
• no_annotations (optional): Exclude location annotations

Example:

Query: "1600 Pennsylvania Avenue, Washington, DC"
Result: JSON with coordinates, formatted address, confidence score, address components, annotations

2. geocode-reverse

Convert coordinates to an address and information about that location

Parameters:

• latitude (required): Latitude coordinate (-90 to 90) in decimal format
• longitude (required): Longitude coordinate (-180 to 180) in decimal format
• language (optional): Language for results
• no_annotations (optional): Exclude location annotations

Example:

Input: 38.8976, -77.0365
Result: "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States of America"

3. get-opencage-info

Check your current API usage and rate limits. NOTE: subscription customers do NOT have hard usage limits. See relevant documentation.

Parameters: None

Returns: Information about remaining requests, rate limits, and reset times.

Available Prompts

geocoding-assistant

A helpful assistant for geocoding tasks. Provides guidance on using the geocoding tools effectively.

Error Handling

The server includes comprehensive error handling:

• Invalid API keys
• Rate limit exceeded
• Network errors
• Invalid coordinates or addresses
• API service unavailable

Environment Variables

• OPENCAGE_API_KEY: Your OpenCage geocoding API key (required)

Troubleshooting

1. "API key required" error: Make sure the env var OPENCAGE_API_KEY is set
2. "No results found": Try a more specific or different address format, see the OpenCage guide to query formatting
3. Rate limit errors: Check your API usage with get-api-status tool
4. Network errors: Verify internet connection or the public OpenCage status page

Relevant Links

• OpenCage homepage - Get your geocoding API key
• OpenCage API Documentation - Full OpenCage geocoding API reference
• Model Context Protocol - Learn more about MCP

Who is OpenCage GmbH?

We run a worldwide geocoding API and geosearch service based on open data. Learn more about us.

We also organize Geomob, a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy the Geomob podcast.