gridpin-mcp — offline geocoding for AI agents

An MCP server that lets an agent geocode addresses with GridPin: one memory-mapped file per country, read on your machine. No API key, no rate limit, and no query leaves the machine. The only network step is downloading a country sheet once, verified against the signed GridPin release.

Countries (release v0.4.0): Brazil, France, Germany, Italy, Netherlands, Serbia, Spain.

Add it to an agent

Claude Code:

$ claude mcp add gridpin -- uvx gridpin-mcp

Any client that reads an mcpServers config (Claude Desktop, Cursor, ...):

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

Tools

Results are the same as the GridPin CLI, Python and DuckDB return. Treat street or city precision as approximate.

Download a sheet without MCP

$ pip install gridpin-mcp
$ gridpin-fetch fr          # prints the path, e.g. ~/.cache/gridpin/v0.4.0/france.bin

import gridpin
from gridpin_mcp import sheets

path = sheets.download("fr")   # no-op when already downloaded
gridpin.Geocoder(str(path)).geocode("1 rue de la Paix, Paris", 1)

Sheets go to $GRIDPIN_HOME, else $XDG_CACHE_HOME/gridpin, else ~/.cache/gridpin. Sizes and SHA-256 of every sheet are pinned in the package from the signed release attestation; a download that does not match is discarded.

License

Apache-2.0. Sheet data: see attributions.