🌍 geo-mcp

Connect Claude or any MCP client to live location intelligence — weather, geocoding, timezone, and nearby places — using only free open APIs.

Live demo on Render • Swagger docs • GitHub repo

What it does

geo-mcp exposes a lightweight MCP surface for real-world geospatial queries. It provides:

geocode_address — address to latitude/longitude
reverse_geocode_coords — location to human-readable address
current_weather — live weather data for any city
location_timezone — timezone and local time for coordinates
places_nearby — nearby points of interest from OpenStreetMap

Built for developers, open source, and fast integration with modern tools.

Tool	Description	API Used
`geocode_address`	Address → lat/lon	Nominatim (OSM)
`reverse_geocode_coords`	lat/lon → address	Nominatim (OSM)
`current_weather`	Live weather for any city	Open-Meteo
`location_timezone`	Timezone + local time	timeapi.io
`places_nearby`	POIs within a radius	Overpass (OSM)

All APIs are free and open — no signup, no keys, no rate-limit surprises for personal use.

Quick start

git clone https://github.com/fjollei/geo-mcp
cd geo-mcp
pip install -r requirements.txt
python server.py

Run with Docker

docker build -t geo-mcp .
docker run -p 8000:8000 geo-mcp

Live demo

Live geo-mcp on Render

Deploy as an HTTP service

This repo now includes app.py, a lightweight HTTP wrapper around the same adapter logic used by the MCP server. It is useful for Render and other container hosts.

Health check: /healthz
Swagger UI: /docs
OpenAPI JSON: /openapi.json
Reverse proxy docs: /redoc
Geocode: /geocode?address=...
Reverse geocode: /reverse-geocode?lat=...&lon=...
Weather: /weather?city=...
Timezone: /timezone?lat=...&lon=...
Nearby places: /places?lat=...&lon=...&category=...&radius_m=...

Connect to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "geo-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/geo-mcp/server.py"]
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop — you'll see the 🔨 tools icon appear.

Example prompts

Once connected, try these in Claude:

What's the weather like in Tokyo right now?

Find me hospitals within 500m of the Eiffel Tower.

What time is it right now in lat 35.6762, lon 139.6503?

Geocode "1600 Pennsylvania Ave NW, Washington DC"

Project structure

geo-mcp/
├── server.py              # FastMCP server + tool definitions
├── adapters/
│   ├── geocoding.py       # Nominatim geocoder
│   ├── weather.py         # Open-Meteo weather
│   ├── timezone.py        # timeapi.io timezone
│   └── places.py          # Overpass POI search
├── requirements.txt
├── Dockerfile
└── claude_desktop_config.json

Tool reference

`geocode_address(address: str)`

{
  "display_name": "Paris, Île-de-France, France",
  "lat": 48.8566,
  "lon": 2.3522,
  "type": "city"
}

`current_weather(city: str)`

{
  "city": "London",
  "temperature_c": 14.2,
  "feels_like_c": 12.8,
  "humidity_pct": 76,
  "wind_speed_kmh": 18.4,
  "condition": "Partly cloudy",
  "precipitation_mm": 0.0
}

`places_nearby(lat, lon, category, radius_m)`

Supported categories: restaurant, cafe, hospital, pharmacy, school, supermarket, park, hotel, bank, gas_station

{
  "category": "cafe",
  "count": 8,
  "places": [
    { "name": "Monmouth Coffee", "lat": 51.513, "lon": -0.122, "opening_hours": "Mo-Fr 07:30-18:00" }
  ]
}

Why this project

Built to demonstrate the multi-adapter MCP pattern — the same architecture used in production fleet/telematics MCP servers. Each adapter is:

Independently testable
Easily swappable (swap Nominatim for Google Maps, Open-Meteo for OpenWeather, etc.)
Async-first with httpx
Typed with clear return schemas

This maps directly to real-world MCP server jobs that require connecting multiple vendor APIs under a unified tool layer.

Extending it

Want to add a new data source? Create adapters/yourapi.py:

import httpx

async def your_tool(param: str) -> dict:
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com/...", timeout=10)
        r.raise_for_status()
        return r.json()

Then register it in server.py:

from adapters.yourapi import your_tool

@mcp.tool()
async def exposed_tool_name(param: str) -> dict:
    """Tool description shown to the AI."""
    return await your_tool(param)

Tech stack

FastMCP — MCP server framework
httpx — async HTTP client
Open-Meteo — free weather API
Nominatim — OpenStreetMap geocoding
Overpass API — OpenStreetMap POI data
timeapi.io — timezone lookup

License

MIT

geo-mcp