ystoneman/geospatial-mcp

Geospatial MCP

MCP server for geospatial operations: MGRS conversion, geocoding, weather data, cell tower lookup, and distance calculations.

This tool provides comprehensive location intelligence capabilities, including robust coordinate conversion between MGRS (Military Grid Reference System) and latitude/longitude coordinates, following the MapTools MGRS guide standards.

Features

• ✅ MGRS Conversion: Bi-directional conversion between MGRS and Lat/Long with multiple precision levels
• ✅ Geocoding: Convert place names to coordinates and reverse geocode coordinates to addresses
• ✅ Weather Data: Get current weather and forecasts for any location
• ✅ Cell Tower Lookup: Find nearby cell towers and network types (2G/3G/4G/5G)
• ✅ Distance Calculations: Calculate distances between points using geodesic method
• ✅ Flexible Input: Accepts MGRS coordinates with or without spaces
• ✅ Automatic Normalization: Handles various formatting styles automatically

Supported MGRS Formats

According to the MapTools guide, MGRS coordinates can be expressed at different precision levels:

All formats can be used with or without spaces:

• With spaces: 10S GJ 06832 44683
• Without spaces: 10SGJ0683244683

Note: MGRS coordinates represent the southwest corner of the grid square.

Tools

1. mgrs_to_latlong

Converts MGRS coordinate to latitude and longitude.

Parameters:

• mgrs_coordinate (str): MGRS coordinate (e.g., '10S GJ 06832 44683' or '31UDQ4820006654')
• precision (int, default=6): Decimal places for lat/long results

Example Input:

{
  "mgrs_coordinate": "10S GJ 06832 44683",
  "precision": 6
}

Example Output:

{
  "status": "success",
  "input_mgrs": "10S GJ 06832 44683",
  "normalized_mgrs": "10SGJ0683244683",
  "mgrs_precision": "1m square (1m precision)",
  "latitude": 48.858370,
  "longitude": 2.294481,
  "decimal_precision": 6,
  "note": "Coordinates represent the southwest corner of the grid square"
}

2. latlong_to_mgrs

Converts latitude and longitude to MGRS coordinate.

Parameters:

• latitude (float): Latitude in decimal degrees
• longitude (float): Longitude in decimal degrees
• precision (int, default=5): MGRS precision level (1-5)

MGRS Precision Levels:

• 1 = 10km precision
• 2 = 1km precision
• 3 = 100m precision
• 4 = 10m precision
• 5 = 1m precision (default)

Example Input:

{
  "latitude": 48.8584,
  "longitude": 2.2945,
  "precision": 5
}

Example Output:

{
  "status": "success",
  "input_latitude": 48.8584,
  "input_longitude": 2.2945,
  "mgrs_coordinate": "31UDQ4820006654",
  "precision_level": 5
}

3. validate_mgrs

Validates and normalizes an MGRS coordinate string.

Parameters:

• mgrs_coordinate (str): MGRS coordinate to validate

Example Input:

{
  "mgrs_coordinate": "10S GJ 0683 4468"
}

Example Output:

{
  "status": "valid",
  "input_mgrs": "10S GJ 0683 4468",
  "normalized_mgrs": "10SGJ06834468",
  "mgrs_precision": "10m square (10m precision)",
  "is_valid": true,
  "test_conversion": {
    "latitude": 44.683000,
    "longitude": -106.832000
  },
  "note": "MGRS coordinates represent the southwest corner of the grid square"
}

4. batch_mgrs_to_latlong

Batch conversion using Pydantic models for structured requests.

5. reverse_geocode

Get place name and address information for coordinates (reverse geocoding).

Accepts either MGRS coordinate OR latitude/longitude. Uses OpenStreetMap Nominatim (free, no API key required).

Parameters:

• Either: mgrs_coordinate (str): MGRS coordinate string
• Or: latitude (float) + longitude (float): Decimal degrees

Example Input (Red Square, Moscow):

{
  "latitude": 55.7539,
  "longitude": 37.6208
}

Example Output:

{
  "status": "success",
  "input_type": "Lat/Long",
  "input_mgrs": null,
  "latitude": 55.7539,
  "longitude": 37.6208,
  "place_name": "Красная площадь, Tverskoy District, Moscow, Central Federal District, 109012, Russia",
  "address": {
    "building": null,
    "road": "Красная площадь",
    "suburb": "Tverskoy District",
    "city": "Moscow",
    "county": null,
    "state": "Central Federal District",
    "country": "Russia",
    "country_code": "RU"
  },
  "place_type": "square",
  "osm_id": 123456789
}

Example with MGRS:

{
  "mgrs_coordinate": "37UDB1234567890"
}

Returns: Place name, detailed address components, location type, and OSM ID

6. calculate_distance

Calculate distance between two points using geodesic method (accounts for Earth's curvature).

Each coordinate can be specified as either MGRS or lat/long. Returns distance in multiple units suitable for UK military use.

Parameters:

• Point 1: Either coord1_mgrs OR (coord1_lat + coord1_lon)
• Point 2: Either coord2_mgrs OR (coord2_lat + coord2_lon)

Example Input (MGRS to Lat/Long):

{
  "coord1_mgrs": "31U DQ 48200 06654",
  "coord2_lat": 51.5007,
  "coord2_lon": -0.1246
}

Example Output:

{
  "status": "success",
  "point1": {
    "type": "MGRS",
    "input": "31U DQ 48200 06654",
    "latitude": 48.858370,
    "longitude": 2.294481
  },
  "point2": {
    "type": "Lat/Long",
    "input": "51.5007, -0.1246",
    "latitude": 51.5007,
    "longitude": -0.1246
  },
  "distance": {
    "meters": 343580.23,
    "kilometers": 343.580,
    "miles": 213.521,
    "nautical_miles": 185.518
  },
  "primary_unit": "343.58km",
  "note": "Distance calculated using geodesic method (accounts for Earth's curvature)"
}

Example with both MGRS:

{
  "coord1_mgrs": "31U DQ 48200 06654",
  "coord2_mgrs": "30U XC 99000 83765"
}

Example with both Lat/Long:

{
  "coord1_lat": 48.8584,
  "coord1_lon": 2.2945,
  "coord2_lat": 51.5007,
  "coord2_lon": -0.1246
}

Returns: Distance in meters, kilometers, miles, and nautical miles with primary unit display (metric preferred for UK military)

7. get_weather

Get current weather and 3-day forecast for any location.

Accepts either MGRS coordinate OR latitude/longitude. Uses Open-Meteo API (free, no API key required, open-source).

Parameters:

• Either: mgrs_coordinate (str): MGRS coordinate string
• Or: latitude (float) + longitude (float): Decimal degrees

Example Input:

{
  "latitude": 55.7539,
  "longitude": 37.6208
}

Example Output:

{
  "status": "success",
  "location": {
    "latitude": 55.7539,
    "longitude": 37.6208,
    "timezone": "Europe/Moscow"
  },
  "current_weather": {
    "time": "2025-10-23T14:00",
    "temperature_celsius": 12.5,
    "feels_like_celsius": 10.2,
    "humidity_percent": 75,
    "precipitation_mm": 0.0,
    "cloud_cover_percent": 40,
    "wind_speed_kmh": 15.3,
    "wind_direction_degrees": 180,
    "weather_description": "Partly cloudy",
    "weather_code": 2
  },
  "hourly_forecast": {
    "times": ["2025-10-23T00:00", "2025-10-23T01:00", ...],
    "temperatures": [11.2, 10.8, ...],
    "precipitation_probability": [20, 15, ...],
    "precipitation_mm": [0.0, 0.0, ...]
  },
  "daily_forecast": {
    "dates": ["2025-10-23", "2025-10-24", "2025-10-25"],
    "max_temp": [15.2, 14.8, 16.1],
    "min_temp": [8.5, 9.2, 10.1],
    "precipitation_sum": [2.5, 0.0, 1.2],
    "precipitation_probability": [60, 20, 40],
    "max_wind_speed": [22.5, 18.3, 20.1]
  },
  "data_source": "Open-Meteo API (open-source weather API)",
  "note": "Temperature in Celsius, wind in km/h, precipitation in mm"
}

Example with MGRS:

{
  "mgrs_coordinate": "37U DB 29000 16000"
}

Weather Descriptions: Based on WMO weather codes including clear sky, cloudy, rain, snow, fog, thunderstorms, etc.

Returns: Current conditions, 24-hour hourly forecast, and 3-day daily forecast with temperature, precipitation, wind, and humidity

Setup

Local Development

1. Clone and navigate to the repository:

git clone <repository-url>
cd geospatial-mcp

2. Create virtual environment:

python3 -m venv venv
source venv/bin/activate

3. Set up environment variables:

cp .env.example .env
# Edit .env and add your OPENCELLID_API_KEY (required for cell tower lookup feature)

4. Install dependencies:

pip install -e .
# Or manually:
# pip install pydantic mgrs packaging geopy requests python-dotenv
# pip install git+https://github.com/cohere-ai/north-mcp-python-sdk.git@main

5. Run the server:

python server.py

The server will start on http://0.0.0.0:3020

Deployment with ngrok

To expose the server publicly:

ngrok http 3020

The MCP server will be accessible at the ngrok URL provided in the terminal output.

Usage

This is an MCP (Model Context Protocol) server, which means it's designed to be used through an MCP client, not via direct HTTP REST calls.

Using with North (Cohere)

Once deployed with ngrok, register the server with North using the ngrok URL. The tools will then be available to use through the North platform.

Using with Claude Desktop or Other MCP Clients

Add to your MCP client configuration:

{
  "mcpServers": {
    "geospatial-mcp": {
      "url": "https://your-ngrok-url.ngrok.app"
    }
  }
}

Example Conversions

Famous Locations

Eiffel Tower, Paris:

• MGRS: 31U DQ 48200 06654 or 31UDQ4820006654
• Lat/Long: 48.8584°N, 2.2945°E

Statue of Liberty, NYC:

• MGRS: 18T WL 83070 04736 or 18TWL8307004736
• Lat/Long: 40.6892°N, 74.0445°W

Big Ben, London:

• MGRS: 30U XC 99000 83765 or 30UXC9900083765
• Lat/Long: 51.5007°N, 0.1246°W

Prompts

The tool includes a helpful prompt:

• convert_mgrs_prompt(mgrs_coord): Generates a natural language prompt for converting an MGRS coordinate

Authentication

The server supports user authentication through the North MCP SDK. When authenticated, user information is logged with each tool call. Unauthenticated access is also supported.

Dependencies

• north-mcp-python-sdk - MCP server framework
• pydantic (>=2.11.7) - Data validation and models
• mgrs (>=1.4.6) - MGRS coordinate conversion library
• geopy (>=2.4.0) - Geodesic distance calculations and geocoding
• requests (>=2.31.0) - HTTP library for API calls
• python-dotenv (>=1.0.0) - Environment variable management

API Keys

Most features work without API keys (using free OpenStreetMap and Open-Meteo APIs). However, the cell tower lookup feature requires:

• OpenCellID API Key: Get a free key at opencellid.org
  • Add to .env file: OPENCELLID_API_KEY=your_key_here
  • Optional: Cell tower lookup will return an error if not configured

Technical Details

Coordinate Normalization

The server automatically:

• Removes spaces from MGRS coordinates
• Converts to uppercase
• Validates format before conversion
• Detects precision level

Error Handling

All tools provide detailed error messages with:

• Original input
• Error description
• Expected format examples
• Validation hints

Docker Deployment

Build and run with Docker:

docker build -t mgrs-converter .
docker run -p 3020:3020 mgrs-converter

Troubleshooting

Server doesn't start

1. Check if port 3020 is available: lsof -i :3020
2. Ensure all dependencies are installed: pip list
3. Verify Python version: python --version (requires Python 3.11+)
4. Check if packaging module is installed: pip install packaging

Coordinate conversion fails

1. Verify MGRS format (Grid Zone + Grid Square + coordinates)
2. Check if spaces are causing issues (they shouldn't with updated version)
3. Try the validate_mgrs tool first to verify the coordinate
4. Ensure truncated coordinates are properly formatted

References

• MapTools MGRS Quick Guide
• National Geospatial Intelligence Agency - MGRS Standards
• Model Context Protocol (MCP)
• OpenCellID API
• Open-Meteo Weather API

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.