chuk-mcp-geocoder

chuk-mcp-geocoder

Geocoding & Place Discovery MCP Server via Nominatim/OpenStreetMap.

Provides forward/reverse geocoding, bounding box extraction, nearby places discovery, batch geocoding, route waypoints, and administrative boundary lookup — designed to work alongside other MCP geospatial servers (DEM, STAC, etc.).

This is a demonstration project provided as-is for learning and testing purposes.

Tools

Tool	Description
geocode	Place name to coordinates (lat, lon, bbox, address)
reverse_geocode	Coordinates to place name and address
bbox_from_place	Place name to [west, south, east, north] bbox for DEM/STAC tools
nearby_places	Find places near a coordinate at multiple scales
admin_boundaries	Administrative hierarchy (country, state, county, city, suburb)
batch_geocode	Geocode multiple place names in one call
route_waypoints	Geocode waypoints in order and compute route distances
distance_matrix	Compute haversine distance matrix between multiple points
geocoder_status	Server status and cache statistics
geocoder_capabilities	Full capabilities listing with LLM guidance

Installation

Using uvx (Recommended - No Installation Required!)

The easiest way to use the server is with uvx, which runs it without installing:

uvx chuk-mcp-geocoder

This automatically downloads and runs the latest version. Perfect for Claude Desktop!

Using uv (Recommended for Development)

# Install from PyPI
uv pip install chuk-mcp-geocoder

# Or clone and install from source
git clone <repository-url>
cd chuk-mcp-geocoder
uv sync --dev

Using pip (Traditional)

pip install chuk-mcp-geocoder

Usage

With Claude Desktop

Option 1: Use the Public Server (Easiest)

Connect to the hosted public server at geocoder.chukai.io:

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

{
  "mcpServers": {
    "geocoder": {
      "url": "https://geocoder.chukai.io/mcp"
    }
  }
}

Option 2: Streamable HTTP URL (Local)

Run the server locally and connect via HTTP:

{
  "mcpServers": {
    "geocoder": {
      "url": "http://localhost:8010/mcp"
    }
  }
}

Then start the server:

uvx chuk-mcp-geocoder http

Option 3: Run Locally with uvx

{
  "mcpServers": {
    "geocoder": {
      "command": "uvx",
      "args": ["chuk-mcp-geocoder"]
    }
  }
}

Option 4: Run Locally with pip

{
  "mcpServers": {
    "geocoder": {
      "command": "chuk-mcp-geocoder"
    }
  }
}

Standalone

Run the server directly:

# With uvx (recommended - always latest version)
uvx chuk-mcp-geocoder

# With uvx in HTTP mode
uvx chuk-mcp-geocoder http

# Or if installed locally
chuk-mcp-geocoder
chuk-mcp-geocoder http

Or with uv/Python:

# STDIO mode (default, for MCP clients)
uv run chuk-mcp-geocoder
# or: python -m chuk_mcp_geocoder.server

# HTTP mode (for web access and streamable HTTP)
uv run chuk-mcp-geocoder http
# or: python -m chuk_mcp_geocoder.server http

# HTTP mode with custom host/port
uv run chuk-mcp-geocoder http --host 0.0.0.0 --port 9000

STDIO mode is for MCP clients like Claude Desktop and mcp-cli. HTTP mode runs a web server on http://localhost:8010 for HTTP-based MCP clients.

Usage with MCP CLI

uv run mcp-cli --server geocoder,dem,stac

Then ask:

"Get the elevation profile for Mersea Island"

The LLM will use bbox_from_place or geocode to resolve the location, then pass coordinates to the DEM server.

Configuration

Environment Variable	Description	Default
NOMINATIM_EMAIL	Contact email for Nominatim API	(none)
NOMINATIM_BASE_URL	Custom Nominatim instance URL	https://nominatim.openstreetmap.org
MCP_STDIO	Force stdio transport mode	(auto-detect)

Development

Setup

# Clone the repository
git clone <repository-url>
cd chuk-mcp-geocoder

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

Running Tests

make test              # Run tests
make test-cov          # Run tests with coverage
make coverage-report   # Show coverage report

Code Quality

make lint      # Run linters
make format    # Auto-format code
make typecheck # Run type checking
make security  # Run security checks
make check     # Run all checks

Building

make build           # Build package
make publish-test    # Upload to TestPyPI for testing
make publish-manual  # Manually upload to PyPI (requires PYPI_TOKEN)
make publish         # Create tag and trigger GitHub Actions release

Architecture

Follows the same 5-layer pattern as chuk-mcp-dem:

1. core/nominatim.py — Async HTTP client with rate limiting and LRU cache
2. core/geocoder.py — Async manager with validation and typed dataclass results
3. models/responses.py — Pydantic v2 response models (extra="forbid", to_text())
4. constants.py — All configuration, messages, and metadata
5. tools/*/api.py — MCP tool registration with @mcp.tool() decorators

Public Server

A public instance is hosted at geocoder.chukai.io for easy access:

• URL: https://geocoder.chukai.io/mcp
• Protocol: MCP over HTTPS (Streamable HTTP)
• Free to use: No API key required
• Always up-to-date: Running the latest version

Simply add it to your Claude Desktop config:

{
  "mcpServers": {
    "geocoder": {
      "url": "https://geocoder.chukai.io/mcp"
    }
  }
}

Data Source

All geocoding data comes from OpenStreetMap via the Nominatim API.

• Data license: ODbL 1.0
• API rate limit: 1 request/second (public API)
• Results are cached in-memory (1 hour TTL)

License

Apache-2.0