webcoderz/MCP-Geo

Geocoding MCP server with GeoPY!
📋 System Requirements
- Python 3.6+
📦 Dependencies
Install all required dependencies:
Required Packages
- **fastmcp**: Framework for building Model Context Protocol servers
- **geoPy**: Python library for accessing and geocoding/reverse geocoding locations.
All dependencies are specified in requirements.txt for easy installation.
📑 Table of Contents
- System Requirements
- Dependencies
- MCP Tools
- Getting Started
- Installation Options
- Claude Desktop
- Elsewhere
- Safety Features
- Development Documentation
- Environment Variables
🛠️ MCP Tools
This MCP server provides the following geocoding tools to Large Language Models (LLMs):
geocode_location
- Takes a user-provided address or place name and returns the best match’s latitude, longitude, and formatted address.
- Handles errors gracefully and returns None if the location is not found or if an error occurs.
reverse_geocode
- Takes a latitude and longitude and returns the nearest address.
- Useful for finding descriptive information about a point on the map.
geocode_with_details
- Similar to geocode_location but 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.
- Rate-limited to avoid hitting geocoding service quotas.
reverse_geocode_multiple_locations
- Accepts a list of [lat, lon] pairs to perform reverse geocoding for each.
- Returns a list of dictionaries containing lat, lon, and address or None for unsuccessful lookups, also rate-limited.
distance_between_addresses
- Calculate the distance between two addresses or place names.
- accepts 2 addresses and a unit of measurement (miles/kilometer)
- Returns the distance in the specified unit, or None if either address could not be geocoded.
distance_between_coords
- Calculate the distance between two lat/lon pairs.
- accepts 2 pairs of latitude and longitude and a unit of measurement (kilometer/miles)
- Returns the distance in the specified unit.
🚀 Getting Started
Clone the repository:
📦 Installation Options
You can install this MCP server in either Claude Desktop or elsewhere. Choose the option that best suits your needs.
Option 1: Install for Claude Desktop
Install using FastMCP:
Option 2: Install elsewhere
To use this server anywhere else:
1. Add the following configuration to the settings file:
🔒 Safety Features
• Rate Limiting: Each geocoding call is rate-limited (e.g., 1-second delay) to avoid excessive requests that violate usage limits.
• Error Handling: Catches geopy exceptions (timeouts, service errors) and returns safe None results instead of crashing.
📚 Development Documentation
If you’d like to extend or modify this server:
• Check geo.py for how each tool is implemented and how geopy is integrated.