GridPin offline geocoder

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.8.0): United States, Canada, Germany, France, Italy, Spain, Australia, Mexico, Netherlands, Brazil, Serbia.

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"] } } }

To keep sheets in another directory, pass GRIDPIN_HOME in the server's own environment:

{ "mcpServers": { "gridpin": { "command": "uvx", "args": ["gridpin-mcp"],                               "env": { "GRIDPIN_HOME": "/path/to/sheets" } } } }

Exporting it in your shell is not enough. Some MCP clients start the server with only a few environment variables (clients built on the MCP Python SDK pass HOME, LOGNAME, PATH, SHELL, TERM and USER on macOS and Linux), so GRIDPIN_HOME and XDG_CACHE_HOME from your shell never reach it and sheets go to ~/.cache/gridpin.

download_sheet fetches a whole sheet in one tool call, and the larger sheets can take longer than a client allows for one call (mcp-haystack's MCPToolset, for example, stops after 30 s by default). Raise the client's tool timeout, or download the sheet beforehand in a terminal, with the same GRIDPIN_HOME as the server; the tool then returns at once:

$ uvx --from gridpin-mcp gridpin-fetch fr

Step-by-step setup for agents (requirements, settings, verification): llms-install.md.

If GridPin is useful to you, a star on GitHub helps other people find it.

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.5.0/france.bin

import gridpinfrom gridpin_mcp import sheets
path = sheets.download("fr")   # no-op when already downloadedgridpin.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.