overspan

overspan-mcp

Overspan の MCP（Model Context Protocol）サーバーです。ホスト型 Overpass API を利用できます。Claude、Cursor、その他あらゆる MCP クライアントから、惑星全体を網羅する OpenStreetMap データに、従量制で直接アクセスできます。生の Overpass QL に加え、近隣検索、バウンディングボックス検索、件数カウント、使用状況の確認に使えるヘルパーツールを提供します。

Overspan API キーが必要です。プランは overspan.dev で月額 19 ドルからご利用いただけます。チェックアウト後、アカウントを作成する必要はなく、キーがメールで届きます。

クイックスタート

Claude Code

claude mcp add overspan --env OVERSPAN_API_KEY=YOUR_KEY -- npx -y overspan-mcp

Claude Desktop、Cursor、その他の JSON 設定クライアント

{
  "mcpServers": {
    "overspan": {
      "command": "npx",
      "args": ["-y", "overspan-mcp"],
      "env": {
        "OVERSPAN_API_KEY": "YOUR_KEY"
      }
    }
  }
}

キーはサーバーの env ブロックに記述する必要があります。MCP クライアントは独自の環境でサーバーを起動するため、シェルプロファイルでエクスポートした変数は引き継がれません。キーを含む設定ファイルはすべて秘密情報として扱ってください。Claude Code の .mcp.json では、"OVERSPAN_API_KEY": "${OVERSPAN_KEY}" と記述すると、キーをファイルに保存せず、環境変数に保持できます。

ツール

ツール	機能
overpass_query	生の Overpass QL クエリを実行します。ヘルパーツールでは対応できない場合に使います。
find_nearby	指定した地点から一定の半径内にある、タグフィルターに一致する地物を検索します。
features_in_bbox	バウンディングボックス内にある、タグフィルターに一致する地物を検索します。
count_features	地物を返さずに、指定範囲内の一致件数を数えます。低コストなので、データを取得する前に使ってください。
get_usage	キーのプラン、上限、当月の使用量、最近のリクエストを確認します。使用量は消費しません。

サーバーは、モデルが読み取れる 2 つのリソース（QL のチートシートである overspan://overpass-ql と、公開サーバーとの違いを説明する overspan://differences）と、1 つのプロンプト（write-bounded-overpass-query）も公開しています。

知っておくと便利な動作

• キーは Authorization: Bearer ヘッダーで送信され、URL に含まれることはありません。
• 成功したツールの結果にはすべて、クォータの残量を示す行（[quota] 49998 of 50000 monthly requests remaining）が含まれるため、エージェントはペースを調整できます。get_usage で詳細を確認でき、呼び出しは無料です。
• エラーは、ゲートウェイのエラーコード、その意味、再試行すべきかどうかとともに、平易な言葉で返されます。拒否されたリクエストはクォータを消費しません。また、ループが暴走しても、より高額な請求が発生するのではなく、キーごとのレート上限と同時実行数上限によって制限されます。
• 大きすぎるレスポンスは、モデルのコンテキストに収まるように切り詰められます。Overpass JSON の場合は要素リストが切り詰められ、結果には削除された要素数が示されます。さらに多くのデータが必要な場合は、OVERSPAN_MAX_RESPONSE_CHARS で上限を引き上げてください。
• [timeout:] を指定していないクエリのタイムアウトは 25 秒です。負荷の高いクエリでは明示的に設定してください。ただし、設定できるのは利用プランの上限までです。

環境変数

変数	必須	デフォルト値	用途
OVERSPAN_API_KEY	はい		Overspan API キー
OVERSPAN_API_URL	いいえ	https://api.overspan.dev	API エンドポイントの上書き
OVERSPAN_MAX_RESPONSE_CHARS	いいえ	48000	ツールの結果を切り詰めるしきい値

データライセンス

結果は、Open Database License のもとでライセンスされている OpenStreetMap データです。このデータを表示または派生して公開する場合は、openstreetmap.org/copyright へのリンクを含む、視認可能なクレジット表記が必要です。Overspan のサブスクリプションはホスティングとアクセスの費用を支払うものであり、データの費用を支払うものではありません。また、これらの義務に変更はありません。

開発

npm install
npm run build
npm test

テストスイートでは、クエリビルダー、レスポンスの整形、エラーマッピング、およびメモリ内 MCP クライアントを使った一連の往復処理をテストします。

リンク

• Overspan のドキュメント
• エラーリファレンス
• 使用状況ダッシュボード

Overspan は独立したサービスであり、OpenStreetMap Foundation または Overpass API プロジェクトとは関係ありません。

MIT ライセンスです。