gsi-mcp

An MCP server for Japan's GSI (Geospatial Information Authority) maps, historical aerial imagery, and temporal geospatial research.

AI agents can discover, retrieve, compare, and reason over Japan's geospatial history.

gsi-mcp is a local (stdio) Model Context Protocol server. It lets an AI agent geocode a place, find out which years of aerial photography are available there, and generate same-extent comparison images across periods — so the agent can see how a location has changed over time.

The hard part it solves is period resolution: GSI has no API that answers "which years are available at this point." Historical imagery is served as a set of independent tile layers (1945–50, 1961–69, 1974–78, …), each with different coverage and zoom. gsi-mcp keeps a layer catalog and probes tile existence to resolve availability per location.

Features

Five tools:

Tool	Purpose
search_place	Geocode a place / address / station name to lat/lon (GSI address search)
list_layers	List the available tile layers (period aerial photos + standard map)
list_available_imagery_periods	Probe which photo periods actually exist at a point
render_map	Render a single layer at a point/zoom to an image file
compare_periods	Render two periods side-by-side over the same extent and scale

Generated images carry a red crosshair marker at the center so the agent (and you) can verify the intended target is actually in frame — geocoding a bare station name can land on a nearby district instead. Every image response includes the required GSI attribution.

Install

Requires Go 1.25+ (CGO not needed).

go install github.com/ekkx/gsi-mcp/cmd/gsi-mcp@latest

Or build a static binary from a checkout:

CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/gsi-mcp ./cmd/gsi-mcp

Configure (Claude Code)

Add to your project's .mcp.json (or user MCP config). Assuming gsi-mcp is on your PATH:

{
  "mcpServers": {
    "gsi": {
      "command": "gsi-mcp"
    }
  }
}

The server writes tiles and generated images under the OS user cache dir (~/.cache/gsi-mcp on Linux) by default; override with -cache-dir.

Flags

Flag	Default	Description
-cache-dir	OS user cache dir	Where tiles and rendered images are stored
-concurrency	4	Max concurrent connections to GSI servers
-tiles-max-mb	1024	Tile cache size cap (MB); oldest evicted at startup (0 = unlimited)
-renders-max-mb	256	Generated-image cache size cap (MB); oldest evicted at startup (0 = unlimited)

Example

Find the aerial-photo periods available at Iyo-Hōjō Station, then compare the 1960s with today over the same area, and show me the image.

The agent chains search_place → list_available_imagery_periods → compare_periods, then opens the returned image_path to describe the change.

Layers

https://cyberjapandata.gsi.go.jp/xyz/{id}/{z}/{x}/{y}.{ext}

Layer ID	Period	Zoom	Notes
ort_1928	~1928	13–18	Limited to some urban areas
ort_riku10	1936–1942	13–18	Limited to some urban areas
ort_USA10	1945–1950	10–17	US military; covered areas only
ort_old10	1961–1969	10–17
gazo1	1974–1978	10–17	Oldest near-nationwide coverage
gazo2	1979–1983	10–17	Not nationwide
gazo3	1984–1986	10–17	Not nationwide
gazo4	1987–1990	10–17	Not nationwide
seamlessphoto	latest	2–18	Composite of multiple sources
std	standard map	2–18	Vector-derived line map (labels; not a photo)

Periods can be referenced by ID or by aliases such as 1974-1978, latest, or std.

Caveats

• Geocoding is address-oriented. GSI's address search may ignore a station/facility name and return a nearby district's representative point. Always confirm the returned title and check that the target sits near the center marker in the rendered image.
• Old photos are not pixel-aligned. Orthorectification accuracy of older imagery is limited, so the same bbox can be off by tens of meters. compare_periods produces material for visual/model comparison, not pixel-level overlay.
• No availability API. Period availability is determined by probing tile existence, so results differ by location.
• Output images are JPEG (Go's standard library has no WebP encoder).

Being a good citizen

GSI's tile servers are a free public service. This server limits concurrency, caches tiles locally, retries transient failures with backoff, and sends an explicit User-Agent. Please avoid bulk harvesting.

Attribution & terms

Generated images must be credited as 地理院タイルを加工して作成 (created by processing GSI tiles); the server attaches this automatically. Individual layers may carry additional third-party rights or usage conditions — see the GSI tile terms.

Status

v0.1 — core 5 tools, request limits, tile cache with startup size cap, stdio transport. Planned: transparent overlay, nendophoto{year} (annual photos from 2007), elevation tools, cache TTL.

License

MIT © ekkx. This covers the gsi-mcp source code only; GSI tile data remains subject to GSI's own terms (see above).