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.
- 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).
- Node.js (version 20 or higher)
- OpenCage geocoding API Key: Sign up on the OpenCage website to get a free-trial geocoding API key
- 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
- Install dependencies:
npm install- Set your OpenCage geocoding API key as an environment variable:
export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"- Build the project:
npm run buildAdd 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"
}
}
}
}Note: the first time you run a command you will need to give Claude permission
Convert an address or place name to coordinates and information about that location.
Parameters:
query(required): The address or place name to geocodecountrycode(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
Convert coordinates to an address and information about that location
Parameters:
latitude(required): Latitude coordinate (-90 to 90) in decimal formatlongitude(required): Longitude coordinate (-180 to 180) in decimal formatlanguage(optional): Language for resultsno_annotations(optional): Exclude location annotations
Example:
Input: 38.8976, -77.0365
Result: "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States of America"
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.
A helpful assistant for geocoding tasks. Provides guidance on using the geocoding tools effectively.
The server includes comprehensive error handling:
- Invalid API keys
- Rate limit exceeded
- Network errors
- Invalid coordinates or addresses
- API service unavailable
OPENCAGE_API_KEY: Your OpenCage geocoding API key (required)
- "API key required" error: Make sure the env var
OPENCAGE_API_KEYis set - "No results found": Try a more specific or different address format, see the OpenCage guide to query formatting
- Rate limit errors: Check your API usage with
get-api-statustool - Network errors: Verify internet connection or the public OpenCage status page
- OpenCage homepage - Get your geocoding API key
- OpenCage API Documentation - Full OpenCage geocoding API reference
- Model Context Protocol - Learn more about MCP
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.