MCP Geo

🚀 MCP-Geo

An MCP geocoding server implemented using GeoPY!

🚀 Quick Start

Step 1: Install Required Dependencies

pip install -r requirements.txt

Step 2: Configure Environment Variables (Optional)

Set the following environment variables as needed:

export GEOCODER_PROVIDER="nominatim"  # Optional: nominatim, arcgis, or bing
export NOMINATIM_URL="nominatim.openstreetmap.org"  # Optional: Nominatim domain
export SCHEME="http"  # Optional: http or https
export ARC_USERNAME="your_arcgis_username"  # Optional: ArcGIS username
export ARC_PASSWORD="your_arcgis_password"  # Optional: ArcGIS password
export BING_API_KEY="your_bing_maps_key"  # Required (for Bing only)

Step 3: Run the Server

python server.py

✨ Features

This MCP server provides the following geocoding tools for large language models (LLMs):

geocode_location

• Accepts an address or place name provided by the user and returns the best-matching latitude, longitude, and formatted address.
• Handles errors and gracefully returns None if the location is not found or an error occurs.

reverse_geocode

• Accepts latitude and longitude and returns the nearest address.
• Used to find descriptive information about a point on the map.

geocode_with_details

• Similar to geocode_location, but returns more data, such as bounding boxes and other detailed address information (if supported by the geocoder).

geocode_multiple_locations

• Accepts a list of address strings and returns the latitude and longitude for each address.
• Supports batch processing of multiple locations.

reverse_geocode_multiple_locations

• Accepts a list of latitudes and longitudes and returns the nearest address for each coordinate.
• Suitable for batch reverse geocoding operations.

📦 Installation

System Requirements

• Python 3.6+

Dependencies

Install all the required dependencies:

# Use uv
uv sync

Required Packages

• fastmcp: A framework for building model context protocol servers.
• geoPy: A Python library for accessing and geocoding/reverse geocoding addresses or locations.

All dependencies are listed in requirements.txt for easy installation.

📚 Documentation

To learn how to extend or customize the server, refer to the geo.py and server.py files. You can add more geocoding features or adjust the existing logic as needed.

🔧 Technical Details

Environment Variables

These variables can be set in your shell or configured according to the environment in the MCP settings file. If more customization is needed, edit the geo.py file and add the required geocoder parameters.

🛡️ Safety Features

• All geocoding requests are made via HTTPS by default to ensure secure data transmission.
• Supports rate limiting and API key authentication (for the Bing geocoder).