GridPin offline geocoder MCP server

GridPin

A country in a file — offline forward and reverse geocoding.

Quick start

$ pip install gridpin gridpin-mcp
$ gridpin-fetch fr    # France sheet, 365 MB, checked against the signed release; prints its path

import gridpin
from gridpin_mcp import sheets

g = gridpin.Geocoder(str(sheets.download("fr")))  # no-op once the sheet is downloaded
g.geocode("1 rue de la Paix, Paris", 1)

Countries: br de es fr it nl rs (gridpin-fetch --list). For AI agents there is an MCP server — claude mcp add gridpin -- uvx gridpin-mcp, details in mcp/README.md. Everything after the download runs offline.

GridPin is an offline geocoder: a country in a data file, memory-mapped and ready in milliseconds, with no server, no database import, and no network. It resolves addresses to coordinates (forward) and coordinates to the nearest indexed address (reverse — approximate: streets are indexed by centroid, so each result carries its distance_m). On a single arm64 laptop core, measured on the France sheet: exact address lookups run at ~3,000/s, reverse geocoding at ~1,800/s, and typo-tolerant fuzzy matching much slower — tens of milliseconds per query, so batch it across cores when you feed it messy input. The engine and every query run fully offline — not a byte of what you geocode leaves your machine; the only network step is you downloading a sheet yourself, and a downloaded sheet carries no query data. Because you compute results locally from openly licensed data, you may store them forever, which hosted geocoding APIs typically forbid. If you have considered self-hosting Nominatim (a beefy server, days of import) or an on-prem geocoder license, the alternative here is: download one file, open it on any laptop.

Install

CLI — prebuilt binaries for Linux x8664 (x8664-unknown-linux-gnu), macOS Apple Silicon (aarch64-apple-darwin) and Windows x8664 (x8664-pc-windows-msvc) are attached to every GitHub release; other targets (Intel macOS, Linux arm64/musl, Windows arm) build from source:

$ base=https://github.com/gridpin/gridpin/releases/download/v0.4.0
$ curl -fsSLO "$base/gridpin-aarch64-apple-darwin.tar.gz"
$ curl -fsSLO "$base/gridpin-release-signers"
$ curl -fsSLO https://dl.gridpin.dev/v0.4.0/attestation.json
$ curl -fsSLO https://dl.gridpin.dev/v0.4.0/attestation.json.sig
# the trust root comes from the OTHER channel — see "Verifying a release" for why
$ ssh-keygen -Y verify -f gridpin-release-signers -I gridpin-release \
    -n gridpin-g02 -s attestation.json.sig < attestation.json \
    || { echo "signature does not verify — STOP"; exit 1; }
$ want=$(python3 -c 'import json;print([a["sha256"] for a in json.load(open("attestation.json"))["assets"] if a["name"]=="gridpin-aarch64-apple-darwin.tar.gz"][0])')
$ test "$want" = "$(shasum -a 256 gridpin-aarch64-apple-darwin.tar.gz | cut -d' ' -f1)" \
    || { echo "archive does not match the signed attestation — STOP"; exit 1; }
$ tar xzf gridpin-aarch64-apple-darwin.tar.gz && sudo mv gridpin /usr/local/bin/

Yes, that is longer than curl | tar. Unpacking an archive runs its contents sooner or later, and a checksum published beside the file it describes proves only that the download was not truncated — whoever can replace one can replace both. The four extra lines are what makes it a check.

Or build from source with stable Rust: cargo build --release --manifest-path gridpin/Cargo.toml.

Python — pip install gridpin. This one rests on PyPI's own integrity, not on the signature above: the attestation covers the artifacts we publish ourselves. If you need the signed chain, take the wheel from the GitHub release and verify it the same way as the CLI archive.

Shortened. The full README is on GitHub.