Claude CodeにMapbox MCPを入れて地図・ルート検索を作る

Mapbox MCPサーバーをClaude Codeに追加すると、住所の座標化、ルート検索、到達圏の計算といった位置情報の処理を、Claudeが実際のMapboxデータで行えるようになります。ルートのサンプルを自分で用意しなくても、アプリの地図に流し込むGeoJSONをその場で取得できます。

このページでは接続方法の選び方、最初の動作確認、ツールの使い分け、地図つき機能を作る流れ、権限の絞り方を順に扱います。

接続はホスト型かローカルか

Mapbox MCPサーバーには、Mapboxが運用するホスト型のエンドポイントと、手元でNode.jsとして動かす方法があります。Claude Codeから使うなら、まずホスト型が手軽です。

ホスト型のエンドポイントは https://mcp.mapbox.com/mcp で、通信方式はStreamable HTTPです。READMEのClaude Code向け手順は、起動前に次のコマンドでサーバーを追加するものです。

claude mcp add --transport http mapbox https://mcp.mapbox.com/mcp

READMEの例では登録名が mapbox-mcp-production になっています。名前は自由に決められます。ここでは短い mapbox を使い、以降の権限ルールもこの名前で書きます。

追加したらClaude Codeを起動し、/mcp を開いて接続を初期化します。ブラウザが開くので、Mapboxアカウントでログインして認可画面で許可すると、接続の確認が表示されます。アクセストークンを手で貼る必要はありません。

一方、ローカルで動かす場合はアクセストークンが必須です。トークンはMapboxの無料アカウントを作り、アカウントページで作成するか既定の公開トークンを使います。ローカル版はnpmパッケージ @mapbox/mcp-server として配布されているので、次のように環境変数を渡して登録します。

claude mcp add mapbox \
  --env MAPBOX_ACCESS_TOKEN=YOUR_TOKEN \
  -- npx -y @mapbox/mcp-server

-- より後ろがサーバーの起動コマンドです。Claude Code側のオプション(--env や --scope)と起動コマンドを分けるための区切りになります。

READMEには、Claude Desktop向けのDXTパッケージ、VS Code、Cursor、Gooseの手順も別ガイドとして並んでいます。この記事はClaude Codeに絞ります。

公式プラグインという入口もある

Claudeのマーケットプレイスには、Mapbox製の mapbox プラグインが載っています。説明は「位置情報アプリを作るためのMapboxのスキルとMCPサーバー。ジオ空間ツール、スタイル管理、Web・iOS・Android・AIエージェント向けの実装パターンを含む」というものです。提供元はMapboxで、掲載ページにはインストール数847と表示されています。

つまり選択肢は2つあります。

• MCPサーバーだけを claude mcp add で入れる。データ取得と地図表示のツールが手に入る
• プラグインを入れる。MCPサーバーに加えて、実装パターンをまとめたスキルが付いてくる

地図データを取りたいだけならMCPサーバー単体で足ります。Web・iOS・Androidのどれかで地図機能を組むなら、スキルまで入るプラグインのほうが一式そろいます。プラグインとして入れたMCPサーバーを管理設定が止める場合の挙動は、claude mcp addが失敗する原因で扱っています。

最初に確かめる3つのプロンプト

接続したら、/mcp でmapboxの横にツール数が出ているかを見ます。そのうえで、アプリを書く前にデータの形を確認します。READMEのサンプルプロンプトに沿った例です。

東京駅から浅草寺まで、徒歩と車でルートを出して。距離と所要時間を並べて

徒歩と車の両方を頼むのは、directions_tool が徒歩・自転車・車のプロファイルを持つからです。車は交通状況を反映するか、一般的な所要時間かを選べます。経由地は2〜25地点まで指定できます。

次は到達圏です。

新宿駅から徒歩15分で行ける範囲を地図に出して

到達圏は isochrone_tool の役割で、時間か距離で複数の等値線を作れます。結果は render_map_tool に渡され、対応クライアントではチャット内に操作できる地図が表示されます。READMEはClaude Code、Claude Desktop、VS Code(GitHub Copilot)、Gooseを対応クライアントとして挙げています。

最後に、座標からの周辺情報です。

35.6812, 139.7671 の周辺に何がある? 徒歩10分圏のカフェも

座標から「ここは何か、近くに何があるか、何分で行けるか」を1回で答えるのが ground_location_tool です。リバースジオコーディング、カテゴリ検索、到達圏を組み合わせ、出典つきの型付きレコードを返します。公式はこの種の質問で、逆ジオコーディングとWeb検索をつなぐ代わりにこのツールを使うよう勧めています。

地図が出ない場合は、クライアントがMCP Appsに対応しているかを確認します。非対応でもツールの結果は文字として返るだけで、呼び出し自体は失敗しません。確実に画像が欲しいときは static_map_image_tool を使います。base64のPNG/JPEGを返すので、どのクライアントでも表示できます。

どのツールがどの仕事を受け持つか

ツールは大きく、Mapbox APIを呼ぶもの、オフラインで計算するもの、表示するものに分かれます。アプリの機能から逆引きすると次の対応になります。

上の表のうち後半の4行は、READMEの見出しと説明に基づく対応です。ツールの正確な呼び出し名は /mcp で表示される一覧を見て確かめます。

オフラインのツールはAPIを消費しない

Turf.jsで動くオフラインのツール群があります。距離、方位角、面積、重心、バッファ、ポリゴンの単純化、凸包、最近傍点、ポリゴンの合成・交差・差分などです。Mapbox APIを呼ばないので、計算のたびにAPIを使うことはありません。

距離を測るだけなのにルート検索を使うと、直線距離と道路距離を取り違えます。READMEが示す使い分けはこうです。

• 道路に沿った距離・時間がほしい: directions_tool
• 2点間の直線(大圏)距離でよい: オフラインの距離ツール
• 配送先が圏内か知りたい: オフラインのポリゴン内判定

これはClaudeへの指示にも効きます。「配達可否は距離ツールではなくポリゴン内判定で」と一言添えるだけで、不要なAPI呼び出しを避けられます。

日本語のカテゴリも取得できる

カテゴリIDの一覧は mapbox://categories というリソースで公開され、mapbox://categories/ja で日本語名の一覧が読めます。クライアントがリソースに対応していない場合は、環境変数 CLIENT_NEEDS_RESOURCE_FALLBACK=true を設定すると、resource_reader_tool と category_list_tool が追加されます。Claude Codeは既定のままで問題ありません。

地図つき機能を作る流れ

ここからが、MCPを入れて何が変わるかの本題です。位置情報アプリの開発では、次の順にMCPを使うと手戻りが減ります。

4番目が実用的です。アプリの描画がずれているとき、render_map_tool で描いた正解と見比べれば、データの誤りか描画コードの誤りかを切り分けられます。

自前のGeoJSONを描かせる

render_map_tool は他のMapboxツールを呼ばなくても使えます。自分で用意したポリゴンやマーカーを layers と markers で直接渡せます。次は公式のペイロード例に沿った形です。

{
  "summary": "Downtown delivery zone",
  "layers": [
    {
      "id": "delivery-zone",
      "type": "fill",
      "data": {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.4194, 37.7749],
              [-122.4094, 37.7749],
              [-122.4094, 37.7849],
              [-122.4194, 37.7849],
              [-122.4194, 37.7749]
            ]
          ]
        },
        "properties": {}
      },
      "paint": { "fill-color": "#3b82f6", "fill-opacity": 0.25 }
    }
  ],
  "markers": [
    { "coordinates": [-122.4144, 37.7799], "style": "pin", "popup": "Warehouse" }
  ]
}

レイヤーの type(fill / line / circle / symbol)は、GeoJSONのジオメトリに合わせます。ポリゴンに symbol を指定しても何も描かれません。自前データが描画されないときは、まずここを疑います。

CLAUDE.mdに地図まわりの規約を書く

Claudeに毎回同じ前提を説明しないよう、プロジェクトのCLAUDE.mdに規約を置いておきます。内容はプロジェクトに合わせて変えてください。例えば次のような断片です。

## 地図・位置情報
- 座標は [経度, 緯度] の順で扱う(GeoJSON準拠)。緯度経度の順で渡さない
- ルートの確認には Mapbox MCP の directions を使い、結果は fixtures/routes/ に保存する
- 距離だけが必要なときはルート検索でなくオフラインの距離ツールを使う
- アクセストークンをソースに直書きしない。環境変数から読む

座標の順序は取り違えやすい点です。GeoJSONは経度が先ですが、会話では「緯度、経度」と言うのが普通なので、明文化しておく価値があります。

描画コードはフィクスチャに対して検証させる

実装後は、テストで描画を検証させます。例えば次のように頼みます。

fixtures/routes/tokyo-asakusa.json を読み込んで折れ線を描くコンポーネントを実装して。
実装後に型チェックとテストを実行し、失敗したら直すところまで進めて

検証コマンドを実行して出力を読ませる反復が、Claudeの強みを最も引き出します。地図の見た目はテストしにくいので、座標配列の長さや始点・終点がフィクスチャと一致することをテストで確かめるのが現実的です。

権限を絞って安全に使う

MCPツールの呼び出しは、既定では許可を求められます。地図の確認を繰り返す作業では、読み取り系のツールだけ事前に許可しておくと止まりません。Claude Codeでは mcp__<サーバー名>__<ツール名> の形で許可ルールを書きます。サーバー名の後ろにワイルドカードを置く書き方もできます。

{
  "permissions": {
    "allow": [
      "mcp__mapbox__directions_tool",
      "mcp__mapbox__isochrone_tool",
      "mcp__mapbox__render_map_tool"
    ]
  }
}

これは .claude/settings.json に置く例です。サーバー全体を許可する mcp__mapbox__* も書けますが、ツールが追加されると許可の範囲も自動で広がります。使うツールを名指しすれば、許可の範囲を自分で管理できます。

Mapboxの各APIは、呼び出しがアカウントの利用量に数えられます。READMEは料金や無料枠に触れていないため、本番に近い量を試す前にMapbox側の料金ページで確認してください。オフラインのツールならAPIの利用量は増えません。

つまずきやすい点

• 地図が出ずにJSONだけ返る: クライアントがMCP Appsに非対応です。static_map_image_tool に切り替えます
• ポリゴンが描かれない: レイヤーの type とジオメトリの組み合わせが合っていません
• ホスト型の認証が済んでいない: /mcp を開いてmapboxを選び、認証の手順をやり直します
• 登録したのにツールが見えない: 同じ名前を別のスコープにも登録していないかを claude mcp list で確かめます

自分でMCPサーバーを作る側に回りたいときは、mcp-server-devプラグインの使い方が出発点になります。同じ形で別の業務ツールを繋ぐ例は、Bitrise MCPのビルド調査にあります。

まとめ

Mapbox MCPは、地図アプリを書く前に実データの形を固め、書いた後に正解の地図と見比べるために使うと効果が出ます。ツールを呼ぶ回数は、オフライン計算で済む処理を切り分けるだけで減らせます。接続はホスト型の1行で始め、CLAUDE.mdに座標の順序を書き、許可ルールは使うツールだけに絞る。この3点が最初の一歩です。