# geojp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/55tarkun/geojp-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/geojp

## Description
MCP server for Japan geodata: cadastral lot numbers (chiban) and reverse geocoding, for AI agents.

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "geojp": {
    "command": "npx",
    "args": ["-y","geojp-mcp"]
  }
}
```

## Documentation & README

# geojp-mcp

*[日本語版 README はこちら](https://github.com/55tarkun/geojp-mcp/blob/HEAD/README.ja.md)*

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](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.
- **[ReverseGeoJP](https://reversegeojp.com)** — 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](https://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)

```bash
npm install -g geojp-mcp
```

or, from source:

```bash
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

```bash
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`:

```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:

```bash
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

```bash
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)

```bash
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