GridPin offline geocoder

io.github.gridpinPublished by GitHub account gridpinv0.5.0Updated Nov 7, 2026

Offline geocoding and reverse geocoding from one local file per country. No API key, no rate limit.

VerifiedSTDIODesktop onlyLocation & LifestyleFiles & Storage

Overview

AI-generated overview

Offline geocoding and reverse geocoding MCP server that reads one local per-country sheet, with no API key or rate limit.

What you can do
  • List covered countries, sheet sizes and which sheets are already downloaded
  • Download a country sheet once, verified by SHA-256 (the only network step)
  • Geocode address text into ranked candidates with latitude, longitude, precision and confidence
  • Reverse-geocode coordinates into nearest indexed addresses with distance in metres
  • Batch-geocode up to 1000 addresses of one country per call, returned in input order
When to use it
Useful when an assistant needs to turn addresses into coordinates or coordinates into addresses without sending queries to a third-party geocoding API, and when the needed country is among the covered sheets (United States, Canada, Germany, France, Italy, Spain, Mexico, Netherlands, Brazil, Serbia at release v0.7.0).
Requirements
Runs locally over stdio, started with uvx from the gridpin-mcp PyPI package, so a Python/uv runtime is needed. The first use of a country requires a network download of its sheet (32-677 MB), stored in GRIDPIN_HOME, else XDG_CACHE_HOME/gridpin, else ~/.cache/gridpin; GRIDPIN_HOME must be set in the server's own environment, not just the shell. No account or API key.
Before you install
Downloading a sheet writes large files (up to 677 MB) to local disk and is the only network activity; large sheets can exceed a client's default tool timeout. Results at street or city precision are approximate and should not be treated as exact. No credentials are requested.

Installation

In SourceWeft

  1. Open GridPin offline geocoder in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

console
$ claude mcp add gridpin -- uvx gridpin-mcp

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

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

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

json
{ "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:

console
$ 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

ToolWhat it does
list_countriescovered countries, sheet sizes, which are downloaded
download_sheetfetch one country sheet (32-677 MB) once, verify its SHA-256; the only tool that uses the network
geocodeaddress text -> ranked candidates with lat, lon, precision, confidence
reversecoordinates -> nearest indexed addresses with distance_m
batchup to 1000 addresses of one country per call, in input order

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

Download a sheet without MCP

console
$ pip install gridpin-mcp$ gridpin-fetch fr          # prints the path, e.g. ~/.cache/gridpin/v0.5.0/france.bin
python
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.

Source: mcp/README.md at commit 831d941

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

4
  1. v0.5.0LatestNov 7, 2026
  2. v0.4.0Nov 3, 2026
  3. v0.3.0Oct 31, 2026
  4. v0.1.0Oct 15, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts