Opencage Geocoding MCP

🚀 OpenCage Geocoding MCP Server

An MCP (Model Context Protocol) server that leverages the OpenCage geocoding API to offer geocoding capabilities. This server enables seamless conversion between addresses and geographic coordinates.

⚠️ Important Note

The examples presented here are based on an integration with claude.ai's desktop client. While the MCP concept is supported by other services, it may necessitate a slightly different configuration.

✨ Features

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

📦 Installation

Prerequisites

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

Steps

1. Clone the repository and navigate to 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 the dependencies:

npm install

This is sufficient to get the MCP working with Claude Desktop (see below).

If you plan to develop the MCP and query it from the command line, you'll also need to: 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 Examples

Basic Usage - Using within Claude Desktop

Add the following 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"
      }
    }
  }
}

Advanced Usage - Available Tools

Note: the first time you run a command, you'll need to grant 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 prompts:

Prompt: "What are the coordinates of Trafalgar Square, London?"
Result: coordinates, timezone, local currency, etc

Prompt: "Where is Les Vans, France? Which Department is it in?"
Result: coordinates, and correct answer that Les Vans is in the Ardèche department

Prompt: "In welchem Bundesland liegt Weimar?"
Result: coordinates, and correct answer that Weimar is in Thüringen

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

Prompt: "what is the address at 38.8976, -77.0365?"
Result: "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States of America"

Prompt: "Which province are the coordinates 41.38700, 2.16995 in?"
Result: "Coordinates are in Barcelona in the province of Catalonia"

3. get - opencage - info

Check your current API usage and rate limits. NOTE: subscription customers do NOT have hard usage limits. See [relevant documentation](https://opencagedata.com/api#rate - limiting). Parameters: None. Returns: Information about remaining requests, rate limits, and reset times.

Available Prompts

geocoding - assistant

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

🔧 Technical Details

Error Handling

The server includes comprehensive error handling for the following scenarios:

• 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: Ensure the environment variable OPENCAGE_API_KEY is set.
2. "No results found": Try a more specific or different address format. Refer to [the OpenCage guide to query formatting](https://opencagedata.com/guides/how - to - format - your - geocoding - query).
3. Rate limit errors: Check your API usage with the get - api - status tool.
4. Network errors: Verify your internet connection or the public OpenCage status page.

📚 Documentation

Relevant Links

• OpenCage homepage - Get your geocoding API key.
• OpenCage API Documentation - Full OpenCage geocoding API reference.
• [OpenCage MCP tutorial](https://opencagedata.com/tutorials/geocode - inside - an - llm - via - mcp).
• Model Context Protocol - Learn more about MCP.

Who is OpenCage GmbH?

We operate 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 strive to highlight geo - innovation. If you're into geo stuff, you'll likely enjoy the Geomob podcast.