📌Overview

Purpose: The MCP-Geo framework is designed to facilitate geocoding operations for Large Language Models (LLMs) through a robust server integrating multiple geographic data services.

Overview: MCP-Geo provides an efficient geocoding server using the GeoPY library to perform a variety of location-based queries. It allows users to retrieve geographic coordinates from addresses, find addresses from coordinates, and calculate distances between locations, ensuring user-friendly handling of errors and rate limits.

Key Features:

• geocode_location: Returns the latitude, longitude, and formatted address for a user-provided address or place name, ensuring graceful error handling.

• reverse_geocode: Finds the nearest address given a set of latitude and longitude coordinates, providing detailed geographic context.

• distance_between_addresses: Calculates the distance between two addresses, allowing users to specify the measurement unit, which can enhance navigation and logistics applications.

• Multiple Requests Handling: Supports batch processing through functions like geocode_multiple_locations and reverse_geocode_multiple_locations, optimizing service usage and adhering to rate limits.

---

MCP-Geo

Geocoding MCP server with GeoPY!

📋 System Requirements

• Python 3.6+

📦 Dependencies

Install all required dependencies:

uv sync

Required Packages

• fastmcp: Framework for building Model Context Protocol servers
• geoPy: Python library for accessing and geocoding/reverse geocoding locations.

📑 Table of Contents

• System Requirements
• Dependencies
• MCP Tools
• Getting Started
• Installation Options
• Safety Features
• Development Documentation
• Environment Variables

🛠️ MCP Tools

geocode_location

• Returns the best match’s latitude, longitude, and formatted address from a user-provided address or place name.

reverse_geocode

• Returns the nearest address for a given latitude and longitude.

geocode_with_details

• Returns additional data such as bounding boxes and detailed address info when supported by the geocoder.

geocode_multiple_locations

• Accepts a list of address strings and returns results for each.

reverse_geocode_multiple_locations

• Accepts a list of latitude and longitude pairs and returns corresponding addresses.

distance_between_addresses

• Calculates the distance between two addresses, returning the distance in specified units.

distance_between_coords

• Calculates the distance between two latitude/longitude pairs.

🚀 Getting Started

Clone the repository:

git clone https://github.com/webcoderz/MCP-Geo.git
cd MCP-Geo

📦 Installation Options

You can install this MCP server for either Claude Desktop or other environments.

Option 1: Install for Claude Desktop

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

Option 2: Install elsewhere

Add the following configuration to the settings file:

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

🔒 Safety Features

• Rate Limiting: Each geocoding call is rate-limited to avoid excessive requests.
• Error Handling: Catches exceptions and returns safe None results instead of crashing.

📚 Development Documentation

• Check geo.py for tool implementation and geopy integration.
• Adjust environment variables to switch providers (Nominatim, ArcGIS, Bing, etc.).
• Refer to geopy’s documentation for advanced usage.

⚙️ Environment Variables

Variable	Description	Default
GEOCODER_PROVIDER (optional)	"nominatim", "arcgis", or "bing"	nominatim
NOMINATIM_URL (optional)	Domain for Nominatim	nominatim.openstreetmap.org
SCHEME (optional)	http/https	http
ARC_USERNAME (optional)	ArcGIS username	None
ARC_PASSWORD (optional)	ArcGIS password	None
BING_API_KEY (required for Bing)	Your Bing Maps key.	None

These can be set in your shell or in the MCP settings file for your environment.