MCP Geocoding Tutorial

This tutorial shows how to use the OpenCage Geocoding API in an LLM via Model Context Protocol (MCP) server. This allows the LLM to call our geocoding API and then work with the API response.

The example shown here is based on an integration with the claude.ai desktop client, and we assume you have that installed. MCP as a concept is supported by other AI services, but may require a slightly different configuration. Learn more about MCP on Wikipedia.

Background

The code examples below will use your geocoding API key once you log in.

Before we dive in to the tutorial

  1. Sign up for an OpenCage geocoding API key.
  2. Play with the demo page, so that you see the actual response the API returns.
  3. Browse the API reference, so you understand the optional parameters, best practices, possible response codes, and the rate limiting on free trial accounts.

Installing the MCP server on your computer

  1. clone the git repository

    The MCP server code is open source and hosted on GitHub.

    $ git clone git@github.com:OpenCageData/opencage-geocoding-mcp.git
    # or
    $ git clone https://github.com/OpenCageData/opencage-geocoding-mcp.git
    
  2. switch into the repository directory

    $ cd opencage-geocoding-mcp

  3. install dependencies

    You will need to have npm installed. Then run:

    $ npm install

  4. configure Claude Desktop

    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. Select Settings > Developer > Edit Config

    This is how Claude knows the MCP is available, how to call it, and how the LLM knows your OpenCage geocoding API key.

    Add this configuration:

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

    Be sure to edit the args entry so it points to the directory where you installed the MCP.

  5. restart Claude Desktop

    So that the new configuration is used.

Using the MCP

You should now be able to make geocoding requests from within Claude Desktop simply by formulating a prompt involving geocoding.

For example try geocode the coordinates 52.5432379, 13.4142133

Note that the first time the MCP is used you will be prompted to give permission.

Grant permission

The LLM should recognize that this request can be answered by the MCP and hand the query off to our geocoding API

Grant permission

You can expand the response to get more details, including the actual API request if you want to see the full JSON response returned by the API.

Grant permission

Send us your feedback

As with all things inthe realm of API, this space is evolving very quickly. It's not currently entirely clear what the exact best practices are, nor what information we should make available to the LLM. Please let us know how you are using the MCP and if there are things we can change to make the service more useful.

Start your free trial

2,500 geocoding API requests/day - No credit card required