{
  "markdown": "# geojp-mcp\n\n*[日本語版 README はこちら](./README.ja.md)*\n\nAn 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):\n\n- **[ChibanJP](https://chibanjp.com)** — 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.\n- **[ReverseGeoJP](https://reversegeojp.com)** — coordinates ⇄ Japanese address (reverse geocoding / forward geocoding).\n\n## Why chiban?\n\nJapan 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.\n\nChiban 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.\n\n## Tools\n\n| Tool | Backing API | Input | Returns |\n| :--- | :--- | :--- | :--- |\n| `get_parcel` | ChibanJP `/parcel` | `lat`, `lon` | Chiban (cadastral lot number), ōaza/aza, municipality, and survey precision class for the containing parcel |\n| `reverse_geocode` | ReverseGeoJP `/reverse` | `lat`, `lon` | Nearest residential address (prefecture, municipality, district, postal code) |\n| `geocode` | ReverseGeoJP `/geocode` | `address` | Up to 10 candidate locations for a partial address match |\n| `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) |\n\nAll tools share a single API key. Get one at [reversegeojp.com](https://reversegeojp.com).\n\n## Two ways to run it\n\nThe tool definitions live in `src/tools.ts` and are shared by both entry points:\n\n- **Local (stdio)** — `src/index.ts`. Your MCP client launches it as a child process on your machine. One user, one API key.\n- **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.\n\n## Setup (local/stdio)\n\n```bash\nnpm install -g geojp-mcp\n```\n\nor, from source:\n\n```bash\nnpm install\nnpm run build\n```\n\nThe 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).\n\n### Register with Claude Code\n\n```bash\nclaude mcp add --scope user geojp -e GEOJP_API_KEY=your-api-key-here -- npx geojp-mcp\n```\n\n`--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`.\n\n**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`.\n\nOr configure manually in `.mcp.json` / `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"geojp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"geojp-mcp\"],\n      \"env\": {\n        \"GEOJP_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Register with Claude Desktop\n\nAdd 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.\n\n## Setup (remote/HTTP)\n\nConnect directly to the hosted server with your own API key — no install or build required:\n\n```bash\nclaude mcp add --scope user --transport http geojp-remote https://mcp.reversegeojp.com --header \"Authorization: Bearer your-api-key-here\"\n```\n\nHealth check: `GET https://mcp.reversegeojp.com/health`.\n\n### Remote server design notes\n\n- **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).\n- **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.\n- **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.\n\n### Deploy / local dev\n\n```bash\nnpm run worker:dev     # local wrangler dev server (http://127.0.0.1:8787 etc.)\nnpm run worker:check   # typecheck against the Workers tsconfig only\nnpm run worker:deploy  # deploy to production\n```\n\n## Smoke test (no API key required — wiring check only)\n\n```bash\nnpm run smoke-test\n```\n\nStarts the server with a dummy key and confirms the tool list loads and a real API call correctly returns an `invalid_api_key` error.\n\n## Why this exists\n\nReverseGeoJP/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.\n\n## License\n\nMIT\n",
  "bytes": 6217,
  "sha": "dd3105d2229f160852e5e7eb9f12e0d2e7b6a35418645b4d858dabc0760e416c",
  "repo_slug": "55tarkun/geojp-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_55tarkun_geojp_e3f5e15b/readme"
}