OpenStreetMap MCP Server

OpenStreetMap MCP サーバー

概要

これは Go 製の OpenStreetMap MCP サーバーです。Model Context Protocol を実装し、LLM が地理空間データを操作できるようにします。

精度、パフォーマンス、保守性、および MCP デスクトップクライアントとの統合のしやすさを重視しています。

機能

このサーバーは、以下を含む OpenStreetMap データを操作するツールを LLM に提供します。

• 住所や地名を座標にジオコーディングする
• 座標を住所に逆ジオコーディングする
• 近くのランドマークを検索する
• ルートを計算し、地点間の道順を取得する
• バウンディングボックス内でカテゴリ別に場所を検索する
• 複数人にとって最適な集合場所を提案する
• エリアを探索し、場所に関する包括的な情報を取得する
• 場所の近くにある EV 充電ステーションを検索する
• ルート沿いにある EV 充電ステーションを検索する
• 自宅と職場間の通勤手段を分析する
• 近隣の住みやすさを分析する
• 場所の近くにある学校を検索する
• 駐車施設を検索する

実装済みのツール

ツール名	説明	パラメーターの例
bbox_from_points	指定されたすべての地理座標を包含するバウンディングボックスを作成します	{"points": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}]}
centroid_points	座標の集合の地理的重心（平均中心）を計算します	{"points": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}]}
enrich_emissions	ルートの選択肢に、CO2 排出量、消費カロリー、費用の推定値を追加します	{"options": [{"mode": "car", "distance": 5000}, {"mode": "bike", "distance": 4500}]}
filter_tags	指定されたタグで OSM 要素を絞り込みます	{"elements": [...], "tags": {"amenity": ["restaurant", "cafe"]}}
geocode_address	住所または場所の名前を地理座標に変換します	{"address": "1600 Pennsylvania Ave, Washington DC"}
geo_distance	2 つの地理座標間の距離を計算します	{"from": {"latitude": 37.7749, "longitude": -122.4194}, "to": {"latitude": 37.8043, "longitude": -122.2711}}
get_map_image	分析用に OpenStreetMap の画像を取得して表示します	{"latitude": 37.7749, "longitude": -122.4194, "zoom": 14}
osm_query_bbox	タグフィルターを使って、バウンディングボックス内の OpenStreetMap データを検索します	{"bbox": {"minLat": 37.77, "minLon": -122.42, "maxLat": 37.78, "maxLon": -122.41}, "tags": {"amenity": "restaurant"}}
polyline_decode	エンコードされたポリライン文字列を一連の地理座標にデコードします	{"polyline": "a~l~FfynpOnlB_pDhgEhjD"}
polyline_encode	一連の地理座標をポリライン文字列にエンコードします	{"points": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}]}
reverse_geocode	地理座標を人が読める住所に変換します	{"latitude": 38.8977, "longitude": -77.0365}
route_fetch	OSRM ルーティングサービスを使って、2 地点間のルートを取得します	{"start": {"latitude": 37.7749, "longitude": -122.4194}, "end": {"latitude": 37.8043, "longitude": -122.2711}, "mode": "car"}
route_sample	指定した間隔でルート上の地点をサンプリングします	{"polyline": "a~l~FfynpOnlB_pDhgEhjD", "interval": 100}
sort_by_distance	基準地点からの距離順に OSM 要素を並べ替えます	{"elements": [...], "ref": {"latitude": 37.7749, "longitude": -122.4194}}
find_nearby_places	特定の場所の近くにあるポイント・オブ・インタレストを検索します	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000, "category": "restaurant", "limit": 5}
get_route_directions	地点間のルートについて、詳細なターンバイターンの道順を取得します	{"start_lat": 37.7749, "start_lon": -122.4194, "end_lat": 37.8043, "end_lon": -122.2711, "mode": "car"}
suggest_meeting_point	複数人にとって最適な待ち合わせ場所を提案します	{"locations": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}], "category": "cafe", "limit": 3}
explore_area	エリアを調査し、そのエリアに関する包括的な情報を取得します	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000}
find_charging_stations	場所の近くにある電気自動車用充電ステーションを検索します	{"latitude": 37.7749, "longitude": -122.4194, "radius": 5000, "limit": 10}
analyze_commute	自宅と職場の間の交通手段を分析します	{"home_latitude": 37.7749, "home_longitude": -122.4194, "work_latitude": 37.8043, "work_longitude": -122.2711, "transport_modes": ["car", "cycling", "walking"]}
analyze_neighborhood	不動産や転居の判断に向けて、近隣地域の住みやすさを評価します	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000, "include_price_data": true}
find_schools_nearby	特定の場所の近くにある教育機関を検索します	{"latitude": 37.7749, "longitude": -122.4194, "radius": 2000, "school_type": "elementary", "limit": 5}
find_parking_facilities	特定の場所の近くにある駐車施設を検索します	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000, "type": "surface", "include_private": false, "limit": 5}

新しい地理・ルート関連ツール

v0.1.1 リリースでは、地理・ルート関連の機能が強化されました。

地理ツール

• 境界ボックスの生成：複数の地点を囲む地理的な境界ボックスを作成します。
• 重心の計算：一連の地理座標の平均中心を求めます。
• 距離の計算：ハーバサイン公式を使用して、地理的な地点間の正確な距離を計算します。
• OSM 要素のフィルタリング：タグと距離で OpenStreetMap の要素をフィルタリングし、並べ替えます。

ポリラインツール

• ポリラインのエンコード／デコード：地理座標と Google の Polyline5 形式を相互に変換します。
• ルートのサンプリング：詳細な分析のために、指定した間隔でルート上の地点をサンプリングします。

ルートツール

• ルートの取得：OSRM ルーティングサービスを使用して、地点間のルートを取得します。
• 排出量データの追加：推定 CO2 排出量、消費カロリー、費用のデータをルートの選択肢に追加します。

これらのツールは、位置情報を活用した複雑なアプリケーションを構築するための基本的な地理機能を LLM に提供します。

組み合わせ可能なツール設計

当社の MCP ツールの多くは、組み合わせ可能なプリミティブとして設計されており、開発時には想定されていなかった新しいワークフローを実現できます。複合ツールは、一般的な複雑な処理を効率的に実行するために用意されています。

構成の原則

• 統一されたインターフェース：すべてのツールで、一貫したパラメーター名（例：minLat、maxLon）とデータ構造を使用します
• 単一責任：各ツールは、1 つの処理を適切に実行します
• 出力／入力の互換性：あるツールの出力を、別のツールの入力としてそのまま使用できます
• 機能的な独立性：ツールは、副作用や隠れた依存関係なしに動作します
• 明確なエラーメッセージ：問題が発生した場合、何が問題だったのかを詳細なフィードバックで正確に示します

ワークフローの例

1. ルート沿いの注目スポットを探す：

   bbox_from_points → osm_query_bbox → filter_tags → sort_by_distance
   

2. 最適な待ち合わせ場所を探す：

   centroid_points → find_nearby_places → filter_tags
   

3. ルートの特徴を分析する：

   route_fetch → polyline_decode → route_sample → filter_tags
   

このような構成可能なアプローチにより、LLM は個々のツールだけでは実現できない、新たな機能を生み出せます。たとえば、適切なプリミティブツールを組み合わせれば、カスタムのサーバー側エンドポイントを用意しなくても、「ルート沿いにある、22:00 以降も営業している車いすで利用可能なカフェを、近い順に 5 件表示して」といったクエリを簡単に作成できます。

地図の視覚化機能

MCP サーバーは、次の 1 つのツールを通じて地図の視覚化機能を提供します。

1. get_map_image - 視覚化と分析を向上させる SVG 形式の地図画像を返します

分析用の地図画像

get_map_image ツールは、視覚的な地図表示と詳細なメタデータの両方を提供する地図機能を備えています。このアプローチには、次のような利点があります。

• 視覚的な表示：会話内にインラインで表示される実際の地図タイル画像を返します
• 直接的な視覚化：Claude が地図上の特徴や地理を視覚的に分析できます
• 包括的なメタデータ：正確な座標、境界、縮尺情報を含みます
• 豊富なコンテキスト：OpenStreetMap をさらに確認できる直接リンク付きのテキスト説明を提供します

このツールは、地図タイル画像に加え、地点の座標、オンラインで地図を表示するための直接リンク、地図領域に関する詳細なメタデータを含む構造化されたテキスト説明を返します。そのため、視覚的な分析と包括的な位置情報の把握の両方に適しています。

使用例

ズームレベル 14 でサンフランシスコの地図画像を取得するには、次のようにします。

{
  "name": "get_map_image",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "zoom": 14
  }
}

ツールからの応答には、次の内容が含まれます。

• 会話内にインラインで表示される地図タイル画像
• 地点のテキスト説明と OpenStreetMap への直接リンク
• 地図の正確な座標情報
• 表示範囲の地理的な境界
• 縮尺情報（1 ピクセルあたりのメートル数）

改善されたジオコーディングツール

ジオコーディングツールが強化され、より信頼性の高い結果と優れたエラー処理を提供できるようになりました。

主な改善点

• 住所のスマートな前処理：入力を自動的にサニタイズし、成功率を高めます
• 詳細なエラー報告：エラーコードと役立つ提案を含む、構造化されたエラーレスポンスを返します
• 診断機能の向上：ジオコーディングの問題を追跡するための詳細なログを提供します
• 書式ガイドの改善：適切な入力例を具体的に記載したドキュメントを提供します

ジオコーディングのベストプラクティス

ジオコーディングツールを使用する際に、最適な結果を得るための方法を紹介します。

1. 複雑なクエリを簡潔にする：

   • 悪い例：「Golden Temple (Harmandir Sahib) in Amritsar」
   • 良い例：「Golden Temple Amritsar India」

2. 地理的な情報を追加する：

   • 悪い例：「Eiffel Tower」
   • 良い例：「Eiffel Tower, Paris, France」

3. エラーの提案を確認する：

   • 改善されたエラーレスポンスには、失敗したクエリを修正するための具体的な提案が含まれます

詳細なドキュメントについてはジオコーディングツールガイドを、これらのツールを効果的に使用する方法をAIシステムに案内する例についてはジオコーディング用AIプロンプトを参照してください。

コードアーキテクチャと設計

コードはソフトウェアエンジニアリングのベストプラクティスに従っています。

1. 高い凝集度と低い結合度 - 各パッケージは明確で、対象を絞った責務を担います
2. 関心の分離 - ツール、サーバーロジック、ユーティリティを明確に分離しています
3. DRY（Don't Repeat Yourself） - 共通ユーティリティをpkg/osmパッケージに切り出しています
4. セキュリティ優先 - HTTP クライアントにはタイムアウトと接続数の上限を適切に設定しています
5. UNIX 風の組み合わせやすさ - 強力な方法で組み合わせられる、小さく対象を絞ったツールです
6. 構造化ログ - 一貫したレベルと形式で、すべてのログをslog経由で記録します：
   • Debug：開発者向けの詳細情報、冗長なメッセージ、診断メッセージ
   • Info：通常の運用メッセージ
   • Warn：実行を必ずしも停止させない予期しない状況
   • Error：重大な問題、潜在的または実際の失敗
7. SOLID 原則 - 特に単一責任の原則とインターフェース分離の原則
8. レジストリパターン - 保守性を高めるため、すべてのツールを中央レジストリで定義しています
9. Google Polyline5 形式 - Google の Polyline5 形式を使用した、標準化されたポリラインのエンコード／デコード
10. 正確な地理空間計算 - 適切な許容誤差を用いた、正確なハーバーサイン距離の計算
11. コンテキスト対応の操作 - すべての操作でキャンセルとタイムアウトに適切に対応します

使用方法

インストール

OpenStreetMap MCP サーバーをインストールするには：

オプション 1：ビルド済みバイナリをダウンロードする

最も簡単に始める方法は、リリースページから最新リリースをダウンロードすることです。ご使用のオペレーティングシステムとアーキテクチャに適したバイナリを選択してください。

オプション 2：ソースからビルドする

ソースからビルドする場合：

### Requirements

- Go 1.24 or higher
- OpenStreetMap API access (no API key required, but rate limits apply)

### Building the server

```bash
go build -o osmmcp ./cmd/osmmcp

サーバーの実行

./osmmcp

サーバーは、次のコマンドラインフラグに対応しています。

# Show version information
./osmmcp --version
# The version may differ if built with custom -ldflags

# Enable debug logging
./osmmcp --debug

# Generate a Claude Desktop Client configuration file
./osmmcp --generate-config /path/to/config.json

# Customize rate limits (requests per second and burst)
# Defaults: Nominatim=1 rps/burst 1, Overpass=2 per min/burst 2, OSRM=100 per min/burst 5
./osmmcp --nominatim-rps 1.0 --nominatim-burst 1
./osmmcp --overpass-rps 0.033 --overpass-burst 2
./osmmcp --osrm-rps 1.67 --osrm-burst 5

# Set custom User-Agent string
./osmmcp --user-agent "MyApp/1.0"

ログの設定

サーバーはslogによる構造化ログを使用し、次のように設定されています。

• Debug レベル：--debugフラグで有効化
• デフォルトレベル：Info
• 形式：キーと値のペアを含むテキスト形式
• 出力：標準エラー出力（stderr）

ログ出力例：

2024-03-14T10:15:30.123Z INFO starting OpenStreetMap MCP server version=0.1.0 log_level=info user_agent=osm-mcp-server/0.1.0
2024-03-14T10:15:30.124Z DEBUG rate limiter initialized service=nominatim rps=1.0 burst=1

サーバーが起動し、標準入力／出力で MCP リクエストを待ち受けます。MCP 対応のクライアントや LLM 統合で使用できます。

Claude デスクトップクライアントでの使用

この MCP サーバーは Claude デスクトップクライアントで動作するように設計されています。以下の手順で簡単にセットアップできます。

1. サーバーをビルドします：

   go build -o osmmcp ./cmd/osmmcp
   

2. Claude デスクトップクライアントの設定を生成または更新します：

   ./osmmcp --generate-config ~/Library/Application\ Support/Anthropic/Claude/config.json
   

   これにより、Claude デスクトップクライアントの mcpServers 設定に OSM エントリが追加されます。設定システムは、次の処理を適切に行います。

   • ファイルが存在しない場合は作成します
   • 設定を更新する際に既存のツールを保持します
   • Claude が実行ファイルを見つけられるよう、絶対パスを使用します
   • 破損を防ぐため、JSON の出力を検証します

3. Claude デスクトップクライアントを再起動して、更新した設定を読み込みます。

4. Claude との会話で、OpenStreetMap MCP ツールを使用できるようになります。

設定ファイルは次のようになります。

{
  "mcpServers": {
    "OSM": {
      "command": "/path/to/osmmcp",
      "args": []
    },
  }
}

API の依存関係

このサーバーは、次の外部 API に依存しています。

• Nominatim - ジオコーディング処理用
• Overpass API - OpenStreetMap データのクエリ用
• OSRM - ルート計算用

これらは公開 API のため、API キーは不要です。ただし、サーバーは適切なユーザーエージェントの識別やリクエストのレート制限など、利用ポリシーに従います。

開発

プロジェクト構成

• cmd/osmmcp - メインアプリケーションのエントリーポイント
• pkg/server - MCP サーバーの実装
• pkg/tools - OpenStreetMap ツールの実装とツールレジストリ（25 個のツール）
• pkg/osm - OpenStreetMap API クライアント、レート制限、ポリラインのエンコード、ユーティリティ
• pkg/geo - 地理型、バウンディングボックス、ハバーサイン距離の計算
• pkg/core - HTTP リトライロジック、検証、エラー処理、Overpass クエリビルダー、OSRM サービスクライアントなどのコアユーティリティ
• pkg/cache - API レスポンス用の TTL ベースのキャッシュレイヤー（デフォルトは 5 分）
• pkg/monitoring - Prometheus メトリクス、ヘルスチェック、接続監視、オブザーバビリティ
• pkg/tracing - 分散トレースとデバッグのための OpenTelemetry トレース機能
• pkg/testutil - テスト用ユーティリティとヘルパー
• pkg/version - ビルドメタデータとバージョン情報

新しいツールの追加

新しいツールを追加するには：

1. pkg/tools 内の新規または既存のファイルにツール関数を実装します
2. pkg/tools/registry.go のレジストリにツール定義を追加します

レジストリベースの設計により、複数のファイルを変更せずに新しいツールを簡単に追加できます。すべてのツール定義が一か所に集約されているため、コードベースを保守しやすくなります。

テスト

次のコマンドでテストを実行します：

go test ./...

テストスイートには次のテストが含まれています。

• ポリラインのエンコードとデコードの単体テスト
• サーバーの統合テスト
• 地理計算のテスト
• ロギングユーティリティのテスト

謝辞

この実装は、次の 2 つの優れたソースに基づいています。

• jagan-shanmugam/open-streetmap-mcp - 元となった Python の実装
• MCPLink OSM MCP Server - 追加機能を備えた MCPLink 版

プロジェクトの沿革

当初は @pdfinn によって作成されました。
すべてのコア機能と初期バージョンは、組織移管前に開発されました。

ドキュメント

• GoDoc - API ドキュメントの全文
• ジオコーディングツールガイド - ジオコーディング機能とベストプラクティスの詳細ガイド
• ジオコーディング用 AI プロンプト - ジオコーディングツールを AI と連携するためのシステムプロンプトと例

ライセンス

MIT ライセンス