geojp

geojp-mcp

日本語版 README はこちら

日本固有の地理データ API を 2 つ公開し、AI エージェント（Claude Code、Claude Desktop、その他の MCP クライアント）向けのツールとして提供する MCP（Model Context Protocol）サーバーです。

• ChibanJP — 座標 → 地番（法務局に記録されている正式な地籍上の土地番号）。地番と住居表示は予測可能な形で対応することはほとんどなく、一般的なジオコーダーの多くでは取得できません。
• ReverseGeoJP — 座標 ⇄ 日本語住所（逆ジオコーディング／順ジオコーディング）。

地番が重要な理由

日本では、地図や郵便物に記載される住居表示と、不動産登記、土地取引、法的文書で使われる地籍上の土地番号である地番という、独立した住所体系が 2 つ使われています。この 2 つに予測可能な対応関係はないため、相互変換には対応表ではなく、登記所備付地図データを使った専用の照会が必要です。

地番は、不動産のデューデリジェンス、土地取引プラットフォーム、日本の登記制度に関わるあらゆるワークフローで重要です。日本の不動産への海外投資が増えるにつれ、その必要性も高まっています。世界中で使われているほとんどのジオコーディング API は登記所備付地図データから地番を直接取得していません。そのため、これを独立したツールとして提供しています。

ツール

ツール	接続先 API	入力	返却値
get_parcel	ChibanJP /parcel	lat、lon	座標を含む筆の地番、大字・字、自治体、および測量精度区分
reverse_geocode	ReverseGeoJP /reverse	lat、lon	最寄りの住所（都道府県、市区町村、地区、郵便番号）
geocode	ReverseGeoJP /geocode	address	部分住所に一致する候補位置を最大 10 件
lookup_location	両方、並列実行	lat、lon	住所と地番をまとめて取得します（オーケストレーションの例です。座標が ChibanJP の現在のカバー範囲外の場合は、住所のみを返して成功します）

すべてのツールで同じ API キーを使用します。reversegeojp.com で取得してください。

実行方法は 2 通り

ツール定義は src/tools.ts にあり、どちらのエントリーポイントからも共有されます。

• ローカル（stdio） — src/index.ts。お使いの MCP クライアントが、マシン上で子プロセスとして起動します。ユーザー 1 人、API キー 1 つです。
• リモート（HTTP、Cloudflare Workers） — src/worker.ts。すでに https://mcp.reversegeojp.com にデプロイされており、ビルド手順なしで、各自の API キーを使って誰でも接続できます。

セットアップ（ローカル／stdio）

npm install -g geojp-mcp

または、ソースから実行します。

npm install
npm run build

サーバーは GEOJP_API_KEY 環境変数から API キーを読み込みます。通常はサーバーを直接実行する必要はありません。MCP クライアントがサブプロセスとして起動します（下記を参照）。

Claude Code に登録する

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

--scope user を指定すると、マシン上のすべてのプロジェクトで使えるようになります（省略すると、現在のプロジェクトのみに登録されます）。claude mcp list で確認してください。

引数の順序が重要です：-e／--env は複数の値を受け取るため、サーバー名より前に指定すると、後続の引数まで取り込んでしまいます。add、サーバー名、-e の順にしてください。

または、.mcp.json／~/.claude.json で手動設定します。

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

Claude Desktop に登録する

claude_desktop_config.json の mcpServers セクションに同じブロックを追加し、Claude Desktop を再起動します。4 つのツール（reverse_geocode、geocode、get_parcel、lookup_location）が使えるようになります。

セットアップ（リモート／HTTP）

インストールやビルドは不要です。ご自身の API キーを使って、ホストされているサーバーに直接接続します。

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

ヘルスチェック：GET https://mcp.reversegeojp.com/health。

リモートサーバーの設計メモ

• バインディングなし、ステートレス：Worker はセッション状態を保持せず、Durable Objects も使用しません。呼び出しごとに Authorization ヘッダーから API キーを読み取り、ReverseGeoJP/ChibanJP の本番 API に直接プロキシします。これにより、Durable Objects に必要な有料の Workers プランを避けられるため、追加のインフラコストなしで reverse-geo-jp/chibanjp と同じ無料プランで動作します（agents-sdk で一般的な McpAgent パターンは Durable Objects と有料プランを前提としています）。
• Web 標準のトランスポート：@modelcontextprotocol/sdk の WebStandardStreamableHTTPServerTransport を使用します。Node 専用の StreamableHTTPServerTransport は、Workers ランタイムには存在しない http.IncomingMessage/ServerResponse に依存するためです。
• 注意点：reversegeojp-client/chibanjp-client はデフォルトで、バインドされていない fetch をそのまま保持します（this.fetchImpl = options.fetch ?? fetch）。Cloudflare Workers では、これにより "Illegal invocation" エラーが発生します。createGeojpMcpServer() のクライアントコンストラクターオプションに明示的にバインドした fetch を渡すことで修正しました（src/tools.ts の boundFetch を参照）。また、geojp-api-clients v0.1.1 で上流側も修正済みです（fetch.bind(globalThis)）。geojp-mcp はこのバージョンに依存しており、念のためローカルの boundFetch もフォールバックとして残しています。

デプロイ／ローカル開発

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

スモークテスト（API キー不要 — 配線の確認のみ）

npm run smoke-test

ダミーキーでサーバーを起動し、ツール一覧が読み込まれることと、実際の API 呼び出しで invalid_api_key エラーが正しく返されることを確認します。

このプロジェクトの目的

ReverseGeoJP/ChibanJP はすでに、ドキュメントを読む開発者が直接呼び出すことを想定した API として稼働していました。このプロジェクトでは、AI エージェントが自動的に検出して呼び出せるよう、これらを MCP ツールとして公開します。既存の本番インフラを再利用しながら、MCP とエージェント統合の実践的な経験を積むことができます。

ライセンス

MIT