# MCP Geocoding Tutorial ## OpenCage Geocoding API MCP Tutorial Tutorial for using the OpenCage Geocoding API in MCP - An API for reverse and forward geocoding using open geo data 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 either [claude.ai](https://claude.ai) desktop client or [Cursor](https://cursor.com), 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](https://en.wikipedia.org/wiki/Model_Context_Protocol). ### Background The code examples below will use your geocoding API key once you [log in](https://opencagedata.com/users/sign_in). #### Before we dive in to the tutorial 1. [Sign up](https://opencagedata.com/users/sign_up) for an OpenCage geocoding API key. 2. Play with the [demo page](https://opencagedata.com/demo), so that you see the actual response the API returns. 3. Browse the [API reference](https://opencagedata.com/api), so you understand the [optional parameters](https://opencagedata.com/api#optional-params), [best practices](https://opencagedata.com/api#bestpractices), [possible response codes](https://opencagedata.com/api#codes), and the [rate limiting](https://opencagedata.com/api#rate-limiting) on free trial accounts. Working with AI? We offer an [Agent Skill](https://github.com/OpenCageData/opencage-skills) to make it easy for AI to quickly learn about our geocoding API. ## Installing the MCP server on your computer 1. #### Is MCP the right tool? This MCP is the right tool for small amounts of geocoding, for example while manually prompting an LLM. If however, you want to process larger volumes of data, for example CSV files full of address or coordinates, or connecting to database full of data, it is almost certainly both faster and more affordable to use [our command line tools](https://opencagedata.com/tutorials/geocode-in-cli), or have the LLM write a script to call our API directly. We offer an [Agent Skill](https://github.com/OpenCageData/opencage-skills/blob/master/skills/opencagegeocoding-api/SKILL.md) to train your AI on best practices for working with our geocoding API. 2. #### 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 3. #### Switch into the repository directory cd opencage-geocoding-mcp 4. #### Install dependencies You will need to have [node](https://nodejs.org/) installed. Then run: npm install 5. #### Configure LLM Client You need to share your MCP configuration with your LLM client, such as Claude Desktop or Cursor. The configuration details are how your LLM client knows the MCP is available, how to call it, and which OpenCage geocoding API key to use. Copy this JSON and update it for your installation: { "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. 6. 7. #### Restart the LLM client 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](https://assets.opencagedata.com/assets/tutorials/mcp-permission-9cd72d5929b23104081858b18df7f593aecb8c0eaf7ee5fcb5861281fef9fc4f.png "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](https://assets.opencagedata.com/assets/tutorials/mcp-example1-a8aa8df9eaef752f98b1a32ce4da4518d018dcec88530e7d89e26641a9f26fff.png "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](https://assets.opencagedata.com/assets/tutorials/mcp-example2-9dee0bdd41b8eab006580add483c8a44945d3c2b4c626f2fb47778e47f9c76e9.png "Grant permission") #### Some example prompts - `"Where is Les Vans, France? Which Department is it in?"` - `"What are the coordinates of Trafalgar Square, London?"` - `"What are the coordinates of Pappelallee 78, Berlin?"` - `"What is the address at -36.84694, 174.73662?"` #### Other commands We also provide the following two commands: - `"geocoding-assistant"` provides an overview of how the MCP works and available commands - `"get-opencage-info"` If you are a free-trial user or one-time plan customer this command checks your current API usage and rate limits (subscription customers don't have hard limits, so this information is not returned for them), and also confirms that the API is working well (returning status 200). ## Send us your feedback As with all things in the realm of AI, 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](https://opencagedata.com/contact) how you are using the MCP and if there are things we can change to make the service more useful. ### Further Reading - [OpenCage geocoding API Reference](https://opencagedata.com/api) - [Comparing geocoding services](https://opencagedata.com/guides/how-to-compare-and-test-geocoding-services) - [Cleaning / formatting your forward geocoding query](https://opencagedata.com/guides/how-to-format-your-geocoding-query) - [Geocoding more quickly](https://opencagedata.com/guides/how-to-geocode-more-quickly) - [Geocoding large datasets](https://opencagedata.com/guides/how-to-geocode-large-datasets) - [Geocoding and preserving privacy](https://opencagedata.com/guides/how-to-preserve-privacy-by-showing-only-an-imprecise-location) - [Sample address and coordinate lists for testing](https://opencagedata.com/tools/address-lists)