geojp-mcp

ReverseGeoJP（緯度経度⇔住所変換）と ChibanJP（緯度経度→地番変換）を、AIエージェント（Claude Code / Claude Desktop等）からツールとして呼び出せるようにするMCP（Model Context Protocol）サーバーです。

個人のキャリア開発（AIエージェント/自動化スキルの習得）の一環として作成。経緯は Career_Development を参照。

提供するツール

ツール名	対応API	入力	内容
reverse_geocode	ReverseGeoJP /reverse	lat, lon	最寄りの町丁目の住所（都道府県・市区町村・町域・郵便番号）
geocode	ReverseGeoJP /geocode	address	住所文字列（部分一致）から候補地を最大10件
get_parcel	ChibanJP /parcel	lat, lon	該当する筆の地番・大字・市区町村・測量精度区分
lookup_location	上記2つを並行呼び出し	lat, lon	住所と地番をまとめて返す（オーケストレーション例。ChibanJP対応エリア外でも住所側だけ成功で返る）

APIキーはReverseGeoJP/ChibanJP共通の1本を使用します。reversegeojp.com で取得してください。

構成（ローカル版とリモート版）

ツール定義本体は src/tools.ts に1本化されており、2つのエントリーポイントから共有されています。

• src/index.ts — ローカル版（stdio）。あなたのPCでAIクライアントが子プロセスとして起動する。1人・1APIキー前提
• src/worker.ts — リモート版（Cloudflare Workers）。URLを持つ本物のWebサービスとして公開し、誰でも自分のAPIキーで接続できる。デプロイ済みURL: https://mcp.reversegeojp.com

セットアップ

npm install
npm run build

環境変数 GEOJP_API_KEY にAPIキーを設定して起動します（サーバー自体は各AIクライアントが子プロセスとして起動するので、通常は直接 npm start する必要はありません。下記のクライアント設定を参照）。

Claude Codeへの登録

claude mcp add --scope user geojp -e GEOJP_API_KEY=your-api-key-here -- node C:/work/geojp-mcp/dist/index.js

--scope user を付けるとPC全体（全プロジェクト）から使えるようになります（省略するとカレントプロジェクトのみ）。登録後は claude mcp list で確認できます。

注意（コマンドの順番）: -e（--env）は複数値を受け取れるため、サーバー名より先に置くと後続の引数まで環境変数として飲み込んでしまいます。add の直後にサーバー名、その後に -e、という順序を守ってください。

VSCode拡張版のClaude Codeを使っている場合、claude コマンドがPATHに登録されていないことがあります。その場合は拡張フォルダ内の resources/native-binary/claude.exe をフルパスで直接呼び出してください（例: C:\Users\<user>\.vscode\extensions\anthropic.claude-code-<version>-win32-x64\resources\native-binary\claude.exe。バージョン番号は更新の都度変わります）。

手動でJSON設定（.mcp.json またはユーザー設定 ~/.claude.json）に書く場合は以下の形式です。

{
  "mcpServers": {
    "geojp": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/work/geojp-mcp/dist/index.js"],
      "env": {
        "GEOJP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktopへの登録

claude_desktop_config.json の mcpServers に追記します。

{
  "mcpServers": {
    "geojp": {
      "command": "node",
      "args": ["C:/work/geojp-mcp/dist/index.js"],
      "env": {
        "GEOJP_API_KEY": "your-api-key-here"
      }
    }
  }
}

設定後、Claude Desktopを再起動すると reverse_geocode / geocode / get_parcel / lookup_location の4ツールが使えるようになります。

リモート版（Cloudflare Workers）への登録

デプロイ済みURL https://mcp.reversegeojp.com に、自分のAPIキーをヘッダで渡して接続します。

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

ローカル版と違い、こちらはビルド・起動作業が不要（既にCloudflare上で稼働中）で、他のPC・他のユーザーからも同じURLで使えます。ヘルスチェックは GET /health で確認できます。

リモート版のインフラ・設計メモ

• バインディングなし・ステートレス設計: セッション状態を一切持たず、Durable Objectsも使用していない。呼び出しの都度、リクエストのAuthorizationヘッダからAPIキーを読み、ReverseGeoJP/ChibanJPの本番APIをそのまま呼び出すだけのプロキシ。これによりDurable Objects必須のWorkers有償プランを避け、既存のreverse-geo-jp/chibanjpと同じ無料プランのまま追加コストゼロで運用できる（agents-sdkのMcpAgentを使う「王道」の実装はDurable Objects前提で有償プラン（$5/月〜）が必要になる点に注意）
• Web Standards対応のトランスポートを使用: @modelcontextprotocol/sdkのWebStandardStreamableHTTPServerTransport（server/webStandardStreamableHttp.js）を使用。Node.js専用のStreamableHTTPServerTransportはNode のhttp.IncomingMessage/ServerResponse前提でWorkersでは動かないため、Fetch API（Request/Response）ベースの版を使う必要がある
• ハマった点: reversegeojp-client/chibanjp-clientはデフォルトで裸のfetchをthisなしで保持・呼び出す実装になっており（this.fetchImpl = options.fetch ?? fetch）、Cloudflare Workers上では"Illegal invocation"エラーになる。createGeojpMcpServer()内で明示的にbindしたfetchをクライアントのコンストラクタオプションとして渡すことで回避している（src/tools.tsのboundFetch）。この問題はgeojp-api-clients本体（v0.1.1、fetch.bind(globalThis)に修正）でもソース修正・npm publish済み。geojp-mcpはv0.1.1に依存を更新済みだが、boundFetchは無害なフォールバックとしてそのまま残している

デプロイ・ローカル開発

npm run worker:dev     # ローカルでwrangler devを起動（http://127.0.0.1:8787等）
npm run worker:check   # Workers向けtsconfigで型チェックのみ
npm run worker:deploy  # 本番デプロイ

動作確認（APIキーなしでも配線チェックのみ可能）

npm run smoke-test

ダミーキーでサーバーを起動し、ツール一覧の取得と実際のAPI呼び出し（invalid_api_key エラーが返ることの確認）まで一通り疎通確認します。

なぜ作ったか

ReverseGeoJP/ChibanJPは既に稼働中のAPIプロダクトだが、人間が直接APIドキュメントを読んで叩く前提だった。AIエージェントがツールとして自動発見・呼び出しできるようにすることで、既存資産を活かしながらMCP設計・エージェント連携のスキルを実践的に学ぶことを目的とした。

ライセンス

MIT