Gdal Mcp

gdal-mcp

AI エージェントに GDAL／Rasterio の操作を提供する MCP サーバーです。CRS の選択、リサンプリング方法、クエリ範囲など、手法が重要な操作の実行前に、構造化された根拠を求めるリフレクションミドルウェアを備えています。

インストール

uvx を使用する場合（推奨）

uvx --from gdal-mcp gdal --transport stdio

Docker を使用する場合

docker build -t gdal-mcp .
docker run -i gdal-mcp gdal --transport stdio

ローカル開発

git clone https://github.com/Wayfinder-Foundry/gdal-mcp.git
cd gdal-mcp
uv sync
uv run gdal --transport stdio

MCP クライアントを設定する

Claude Desktop

claude_desktop_config.json に追加します（macOS：~/Library/Application Support/Claude/、 Windows：%APPDATA%\Claude\、Linux：~/.config/Claude/）：

{
  "mcpServers": {
    "gdal-mcp": {
      "command": "uvx",
      "args": ["--from", "gdal-mcp", "gdal", "--transport", "stdio"],
      "env": {
        "GDAL_MCP_WORKSPACES": "/path/to/your/geospatial/data"
      }
    }
  }
}

Claude Desktop を再起動します。MCP サーバーのインジケーターが表示され、raster_* と vector_* のツールを利用できるようになります。

ワークスペースの制限

GDAL_MCP_WORKSPACES は、サーバーが操作を許可されているディレクトリをコロン区切りで指定するリストです。設定されていない場合は、すべてのパスが許可され、警告が記録されます。

任意のツール表示フラグ：RASTER=true、VECTOR=true。すべての設定項目については docs/ENVIRONMENT_VARIABLES.md を参照してください。

ツール

• ラスター： raster_info、raster_convert、raster_reproject、raster_stats、raster_query
• ベクター： vector_info、vector_convert、vector_reproject、vector_clip、vector_buffer、vector_simplify、vector_query
• リソース： カタログ（workspace://...）、メタデータ（metadata://...）、リファレンス（reference://...）、クエリ結果（query://result/{id}）
• プロンプト： justify_crs_selection、justify_resampling_method、justify_query_extent（ほかにも src/prompts/ にあります）

パラメーター、戻り値の形式、実例については TOOLS.md を参照してください。

リフレクションミドルウェア

手法が重要なツールは、呼び出し元のエージェントが構造化された根拠を提示するまで実行を拒否します。処理の流れは次のとおりです。

1. エージェントが、たとえば raster_reproject(dst_crs="EPSG:3857", resampling="cubic", ...) を呼び出します。
2. ミドルウェアが .preflight/justifications/{domain}/ に一致するハッシュがあるかを確認します。
3. 見つからない場合、関連するプロンプト（例：justify_crs_selection）を示すヒントとともに、呼び出しから ToolError が発生します。
4. エージェントがプロンプトを呼び出し、Justification スキーマ（意図、検討した代替案、選択、トレードオフ、確信度）に記入してから、__reflection ペイロードを指定してツールを再度呼び出します。
5. 根拠はドメインごとにキャッシュされるため、EPSG:3857 に関する CRS の根拠は、以降の呼び出しで raster_reproject と vector_reproject の両方に適用されます。

スキーマとキャッシュの構成については docs/REFLECTION.md を、これが存在する理由については docs/PHILOSOPHY.md を参照してください。

ドキュメント

• TOOLS.md — ツールリファレンス
• docs/ENVIRONMENT_VARIABLES.md — 実行時の設定
• docs/REFLECTION.md — リフレクションミドルウェアの内部仕様
• docs/PHILOSOPHY.md — 設計理念と方針
• docs/ROADMAP.md — リリース履歴と方針
• CHANGELOG.md — バージョンごとの変更履歴
• CONTRIBUTING.md — 貢献ガイド

トラブルシューティング

Access denied: path outside allowed workspaces — 「ワークスペースの制限」を参照し、対象のディレクトリを含めるよう GDAL_MCP_WORKSPACES を設定してください。

MCP クライアントにサーバーが表示されない — uvx --from gdal-mcp gdal --help を単独で実行できることを確認し、設定ファイルを編集した後にクライアントを再起動してください。

License

MIT — see LICENSE.

Built on FastMCP, Rasterio, pyogrio, and Shapely.