MCP Geo Server

You run MCP-Geo to add geocoding and reverse geocoding capabilities to your MCP client workflows. Built on GeoPY, it lets you convert addresses to coordinates, find places from coordinates, and compute distances between locations with flexible provider options.

How to use

You interact with MCP-Geo through standard MCP tooling to request geocoding and reverse geocoding operations. Use the geocoding tools to translate addresses or place names into latitude/longitude coordinates, or to retrieve descriptive addresses for a given point. You can also query multiple locations at once and compute distances between addresses or coordinate pairs. If a query cannot be resolved, you receive a safe None result instead of an error.

How to install

Prerequisites: you need Python 3.6 or newer.

Option 1: Install for Claude Desktop

fastmcp install geo.py --name "MCP Geo"

Option 2: Install elsewhere

Add the following MCP configuration to your settings file to run MCP-Geo with UV. This starts the server in the MCP environment and wires the geocoder provider and URL settings.

{
  "mcp-geo": {
    "command": "uv",
    "args": [
      "--directory",
      "MCP-Geo",
      "run",
      "geo.py"
    ],
    "env": {
      "NOMINATIM_URL": "${NOMINATIM_URL}",
      "SCHEME": "http",
      "GEOCODER_PROVIDER": "nominatim"
    }
  }
}

Additional setup notes

Safety features are built in to prevent excessive usage and to handle errors gracefully. The server rate-limits geocoding calls and returns None when a location cannot be found or when a geopy error occurs.

Configuration and environment

Configure the server using environment variables to select the geocoder provider and its options.

Environment variables

GEOCODER_PROVIDER defines the geocoder backend to use: nominatum, arcgis, or bing. NOMINATIM_URL sets the domain for the Nominatim service. SCHEME selects http or https. ARC_USERNAME and ARC_PASSWORD are for ArcGIS, and BING_API_KEY is required for Bing.

Development notes

If you want to extend or modify the server, inspect geo.py to see how each tool is implemented and how geopy is integrated. You can switch providers by adjusting environment variables and consult geopy’s docs for advanced usage like bounding boxes or language settings.

Troubleshooting

Common issues include misconfigured provider settings, missing environment variables, or rate-limited calls. Ensure NOMINATIM_URL and GEOCODER_PROVIDER are set correctly, and verify network access to the chosen geocoder service.

Available tools

geocode_location

Takes a user-provided address or place name and returns the best match’s latitude, longitude, and formatted address.

reverse_geocode

Takes a latitude and longitude and returns the nearest address.

geocode_with_details

Returns additional data such as bounding boxes and more detailed address info, if supported by the geocoder.

geocode_multiple_locations

Accepts a list of address strings and returns a list of geocoding results (lat/lon/address) for each address, with rate-limiting.

reverse_geocode_multiple_locations

Accepts a list of [lat, lon] pairs to perform reverse geocoding for each, returning a list of results or None for unsuccessful lookups.

distance_between_addresses

Calculates the distance between two addresses or place names in the specified unit (miles/kilometer).

distance_between_coords

Calculates the distance between two lat/lon pairs in the specified unit (kilometer/miles).