MCP Geo

1# MCP-Geo
2Geocoding MCP server with GeoPY!
3 
4 
5<a href="https://glama.ai/mcp/servers/ujss4qy5fs">
6  <img width="380" height="200" src="https://glama.ai/mcp/servers/ujss4qy5fs/badge?v=1" />
7</a>
8 
9## 📋 System Requirements
10 
11 
12- Python 3.6+
13 
14## 📦 Dependencies
15 
16Install all required dependencies:
17 
18```bash
19# Using uv
20uv sync
21```
22 
23### Required Packages
24- **fastmcp**: Framework for building Model Context Protocol servers
25- **geoPy**: Python library for accessing and geocoding/reverse geocoding locations.
26 
27 
28All dependencies are specified in `requirements.txt` for easy installation.
29 
30## 📑 Table of Contents
31- [System Requirements](#-system-requirements)
32- [Dependencies](#-dependencies)
33- [MCP Tools](#%EF%B8%8F-mcp-tools)
34- [Getting Started](#-getting-started)
35- [Installation Options](#-installation-options)
36  - [Claude Desktop](#option-1-install-for-claude-desktop)
37  - [Elsewhere](#option-2-install-elsewhere)
38- [Safety Features](#-safety-features)
39- [Development Documentation](#-development-documentation)
40- [Environment Variables](#%EF%B8%8F-environment-variables)
41 
42## 🛠️ MCP Tools
43 
44This MCP server provides the following geocoding tools to Large Language Models (LLMs):
45 
46### geocode_location
47 
48- Takes a user-provided address or place name and returns the best match’s latitude, longitude, and formatted address.
49 
50- Handles errors gracefully and returns None if the location is not found or if an error occurs.
51 
52### reverse_geocode
53 
54- Takes a latitude and longitude and returns the nearest address.
55- Useful for finding descriptive information about a point on the map.
56 
57### geocode_with_details
58 
59- Similar to geocode_location but returns additional data such as bounding boxes and more detailed address info, if supported by the geocoder.
60 
61### geocode_multiple_locations
62 
63- Accepts a list of address strings and returns a list of geocoding results (lat/lon/address) for each address.
64- Rate-limited to avoid hitting geocoding service quotas.
65 
66### reverse_geocode_multiple_locations
67 
68- Accepts a list of [lat, lon] pairs to perform reverse geocoding for each.
69- Returns a list of dictionaries containing lat, lon, and address or None for unsuccessful lookups, also rate-limited.
70 
71### distance_between_addresses
72 
73- Calculate the distance between two addresses or place names.
74- accepts 2 addresses and a unit of measurement (miles/kilometer)
75- Returns the distance in the specified unit, or None if either address could not be geocoded.
76 
77### distance_between_coords
78 
79- Calculate the distance between two lat/lon pairs.
80- accepts 2 pairs of latitude and longitude and a unit of measurement (kilometer/miles)
81- Returns the distance in the specified unit.
82 
83 
84## 🚀 Getting Started
85 
86Clone the repository:
87 
88```bash
89git clone https://github.com/webcoderz/MCP-Geo.git
90cd MCP-Geo
91```
92 
93 
94## 📦 Installation Options
95 
96You can install this MCP server in either Claude Desktop or elsewhere. Choose the option that best suits your needs.
97 
98### Option 1: Install for Claude Desktop
99 
100Install using FastMCP:
101 
102```bash
103fastmcp install geo.py --name "MCP Geo"
104```
105 
106### Option 2: Install elsewhere
107 
108To use this server anywhere else:
109 
110 
1111. Add the following configuration to the settings file:
112 
113```json
114{
115    "mcp-geo": {
116        "command": "uv",
117        "args": [
118          "--directory",
119          "MCP-Geo",
120          "run",
121          "geo.py"
122        ],
123        "env": {
124        "NOMINATIM_URL": "${NOMINATIM_URL}",
125        "SCHEME": "http",
126        "GEOCODER_PROVIDER": "nominatim"
127        }
128    }
129}
130```
131 
132 
133🔒 Safety Features
134	•	Rate Limiting: Each geocoding call is rate-limited (e.g., 1-second delay) to avoid excessive requests that violate usage limits.
135	•	Error Handling: Catches geopy exceptions (timeouts, service errors) and returns safe None results instead of crashing.
136 
137📚 Development Documentation
138 
139If you’d like to extend or modify this server:
140	•	Check geo.py for how each tool is implemented and how geopy is integrated.
141	•	Adjust environment variables to switch providers (Nominatim, ArcGIS, Bing, etc.).
142	•	Look at geopy’s official docs for advanced usage like bounding boxes, language settings, or advanced data extraction.
143 
144⚙️ Environment Variables
145 
146Configure the server using environment variables:
147 
148| Variable             | Description                              | Default            |
149 |----------------------|------------------------------------------|--------------------|
150| `GEOCODER_PROVIDER` (optional)   | "nominatim", "arcgis", or "bing"     | nominatim          |
151| `NOMINATIM_URL` (optional)       | Domain for Nominatim | nominatim.openstreetmap.org       |
152| `SCHEME` (optional)              | http/https    | http               |
153| `ARC_USERNAME` (optional for ArcGIS)        | ArcGIS username            | None               |
154| `ARC_PASSWORD` (optional for ArcGIS)        | ArcGIS password      | None               |
155| `BING_API_KEY` (required for Bing)        | Your Bing Maps key.      | None               |
156 
157These can be set in your shell or in the MCP settings file for your environment. If more are needed just edit geo.py and add them in to whichever geocoder you are using.
158