mcpField
G
GridPin offline geocoder

GridPin offline geocoder

Local
gridpin.devMaps & Travel4Updated today
RepositoryVisit website

About GridPin offline geocoder

GridPin offline geocoder is an MCP server for agents that need address lookup without sending queries off the machine. It uses locally stored, memory-mapped country files and supports geocoding, reverse geocoding and batches.

Key features

  1. 01Offline address geocoding
  2. 02Reverse lookup from coordinates
  3. 03Batch up to 1,000 addresses
  4. 04Country sheets verified by SHA-256

Use cases

  1. 01Find coordinates for an address offline
  2. 02Look up nearby addresses from coordinates
  3. 03Geocode a list of addresses in one country

MCP support

The MCP server provides tools to list covered countries, download and verify country sheets, geocode addresses, reverse geocode coordinates, and process batches. Only downloading a sheet uses the network.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "gridpin-gridpin": {
      "command": "uvx",
      "args": [
        "gridpin-mcp"
      ],
      "env": {
        "GRIDPIN_HOME": "<GRIDPIN_HOME>"
      }
    }
  }
}
Run commanduvx gridpin-mcp
Environment variables to set
GRIDPIN_HOMEDirectory for downloaded country sheets (default: ~/.cache/gridpin)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypigridpin-mcp0.1.0

Tools

5

Saved tool list · updated 2w ago

This tool takes no parameters.

Details

From the project 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.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"] } } }

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

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

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.