io.github.55tarkun/geojp

geojp-mcp

日本語版 README はこちら

An MCP (Model Context Protocol) server that exposes two Japan-specific geodata APIs as tools for AI agents (Claude Code, Claude Desktop, and other MCP clients):

• ChibanJP — coordinates → chiban (地番, the official cadastral lot number recorded at Japan's Legal Affairs Bureau). Chiban rarely maps predictably to a residential address (住居表示) and is not exposed by most general-purpose geocoders.
• ReverseGeoJP — coordinates ⇄ Japanese address (reverse geocoding / forward geocoding).

Why chiban?

Japan uses two independent addressing systems: the residential address (住居表示) that appears on maps and mail, and the chiban — the cadastral lot number used in property registries, land transactions, and legal documents. The two do not follow a predictable pattern, so converting between them requires a dedicated lookup against registry map data, not a lookup table.

Chiban matters for real estate due diligence, land transaction platforms, and any workflow that touches Japan's registry system — a growing need as foreign investment in Japanese real estate rises. Most global geocoding APIs do not source chiban directly from registry map data, which is why this exists as a standalone tool.

Tools

Tool	Backing API	Input	Returns
get_parcel	ChibanJP /parcel	lat, lon	Chiban (cadastral lot number), ōaza/aza, municipality, and survey precision class for the containing parcel
reverse_geocode	ReverseGeoJP /reverse	lat, lon	Nearest residential address (prefecture, municipality, district, postal code)
geocode	ReverseGeoJP /geocode	address	Up to 10 candidate locations for a partial address match
lookup_location	Both, in parallel	lat, lon	Address and chiban together in one call (an orchestration example — succeeds with address-only if the point falls outside ChibanJP's current coverage)

All tools share a single API key. Get one at reversegeojp.com.

Two ways to run it

The tool definitions live in src/tools.ts and are shared by both entry points:

• Local (stdio) — src/index.ts. Your MCP client launches it as a child process on your machine. One user, one API key.
• Remote (HTTP, Cloudflare Workers) — src/worker.ts. Already deployed at https://mcp.reversegeojp.com; anyone can connect with their own API key, no build step required.

Setup (local/stdio)

npm install -g geojp-mcp

or, from source:

npm install
npm run build

The server reads the API key from the GEOJP_API_KEY environment variable. You normally don't run it directly — your MCP client starts it as a subprocess (see below).

Register with Claude Code

claude mcp add --scope user geojp -e GEOJP_API_KEY=your-api-key-here -- npx geojp-mcp

--scope user makes it available across all projects on your machine (omit it to register for the current project only). Verify with claude mcp list.

Argument order matters: -e/--env accepts multiple values, so it will swallow subsequent arguments if placed before the server name. Keep the order: add, then the server name, then -e.

Or configure manually in .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "geojp": {
      "type": "stdio",
      "command": "npx",
      "args": ["geojp-mcp"],
      "env": {
        "GEOJP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Register with Claude Desktop

Add the same block to the mcpServers section of claude_desktop_config.json, then restart Claude Desktop. Four tools (reverse_geocode, geocode, get_parcel, lookup_location) become available.

Setup (remote/HTTP)

Connect directly to the hosted server with your own API key — no install or build required:

claude mcp add --scope user --transport http geojp-remote https://mcp.reversegeojp.com --header "Authorization: Bearer your-api-key-here"

Health check: GET https://mcp.reversegeojp.com/health.

Remote server design notes

• No bindings, stateless: the Worker holds no session state and uses no Durable Objects. Every call reads the API key from the Authorization header and proxies straight through to the ReverseGeoJP/ChibanJP production APIs. This avoids the paid Workers plan that Durable Objects require, so it runs on the same free plan as reverse-geo-jp/chibanjp with no added infrastructure cost (the more common McpAgent pattern from agents-sdk assumes Durable Objects and a paid plan).
• Web Standards transport: uses @modelcontextprotocol/sdk's WebStandardStreamableHTTPServerTransport, since the Node-only StreamableHTTPServerTransport depends on http.IncomingMessage/ServerResponse, which don't exist in the Workers runtime.
• Gotcha: reversegeojp-client/chibanjp-client default to holding a bare, unbound fetch (this.fetchImpl = options.fetch ?? fetch), which throws "Illegal invocation" on Cloudflare Workers. Fixed by passing an explicitly-bound fetch into the client constructor options in createGeojpMcpServer() (see boundFetch in src/tools.ts). Also fixed upstream in geojp-api-clients v0.1.1 (fetch.bind(globalThis)); geojp-mcp depends on that version, and keeps the local boundFetch as a harmless fallback.

Deploy / local dev

npm run worker:dev     # local wrangler dev server (http://127.0.0.1:8787 etc.)
npm run worker:check   # typecheck against the Workers tsconfig only
npm run worker:deploy  # deploy to production

Smoke test (no API key required — wiring check only)

npm run smoke-test

Starts the server with a dummy key and confirms the tool list loads and a real API call correctly returns an invalid_api_key error.

Why this exists

ReverseGeoJP/ChibanJP were already running as APIs meant to be called directly by developers reading the docs. This project exposes them as MCP tools so AI agents can discover and call them automatically — reusing the existing production infrastructure while building hands-on MCP/agent-integration experience.

License

MIT