thomaschi78/opencage-mcp

OpenCage Geocoding MCP Server

A Model Context Protocol (MCP) server that provides geocoding capabilities using the OpenCage Geocoding API. Convert addresses to coordinates (forward geocoding) and coordinates to addresses (reverse geocoding).

This project also includes a command-line tool for batch geocoding a CSV file.

Features

• Forward Geocoding: Convert addresses and place names to geographic coordinates
• Reverse Geocoding: Convert coordinates to human-readable addresses
• Bounded Geocoding: Prioritize results within a specific geographic area
• Batch Geocoding: Process multiple addresses in one request
• Rich Metadata: Get timezone, currency, and other location information
• Multi-language Support: Results in multiple languages
• Country Filtering: Restrict results to specific countries
• CSV Geocoding: A command-line tool to geocode a CSV file of addresses.

Installation

1. Clone or download this repository
2. Install dependencies:

cd opencage-mcp
npm install

3. Set up your API key:

Create a .env file in the opencage-mcp directory with your OpenCage API key:

OPENCAGE_API_KEY=your_api_key_here

Get your free API key at https://opencagedata.com/api

Usage

MCP Server

To run the MCP server:

npm start

To test with the MCP Inspector:

npx @modelcontextprotocol/inspector node index.js

CSV Geocoding Tool

The geocode-csv.js script will read a CSV file from data/input, geocode the addresses, and write the results to data/output.

1. Prepare your input file: Place your CSV file in the data/input directory. The script is pre-configured to read Listas Xande de Pilares - localidades.csv. The CSV should have the columns Estado, Cidade, and Bairro.

2. Run the script:

node geocode-csv.js

The script will display a progress bar and a summary of the geocoding results.

Configuration

Add the server to your MCP settings file:

For Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opencage": {
      "command": "node",
      "args": ["/path/to/opencage-mcp/index.js"],
      "env": {
        "OPENCAGE_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Other MCP Clients

Configure according to your client's documentation, using:

• Command: node
• Args: ["/path/to/opencage-mcp/index.js"]
• Environment: OPENCAGE_API_KEY=your_api_key_here

Available Tools

1. forward_geocode

Convert an address or place name to coordinates.

Parameters:

• query (required): The address or place name
• language (optional): Language code (e.g., 'en', 'fr', 'de')
• limit (optional): Maximum results (default: 10)
• countrycode (optional): Country code filter (e.g., 'us', 'gb')
• no_annotations (optional): Exclude metadata (default: false)

Example:

Query: "1600 Amphitheatre Parkway, Mountain View, CA"

2. reverse_geocode

Convert coordinates to an address.

Parameters:

• latitude (required): Latitude coordinate
• longitude (required): Longitude coordinate
• language (optional): Language code
• no_annotations (optional): Exclude metadata (default: false)

Example:

Latitude: 37.4224764
Longitude: -122.0842499

3. geocode_with_bounds

Geocode with geographic bounds to prioritize results in a specific area.

Parameters:

• query (required): The address or place name
• min_lat (required): Minimum latitude
• min_lng (required): Minimum longitude
• max_lat (required): Maximum latitude
• max_lng (required): Maximum longitude
• limit (optional): Maximum results (default: 10)

Example:

Query: "Springfield"
Bounds: 37.0, -89.0, 40.0, -87.0 (Illinois area)

4. batch_geocode

Geocode multiple addresses at once.

Parameters:

• queries (required): Array of addresses to geocode
• language (optional): Language code
• countrycode (optional): Country code filter

Example:

Queries: [
  "Eiffel Tower, Paris",
  "Big Ben, London",
  "Statue of Liberty, New York"
]

API Limits

The free tier of OpenCage API includes:

• 2,500 requests per day
• Rate limiting is handled by the tool.

For higher limits, check the OpenCage pricing page.

License

MIT