ArcGIS MCP Bridge

arcgis-mcp-bridge

クイックスタート

arcgis-mcp-bridge を利用するには、Windows、ライセンス認証済みの ArcGIS Pro のインストール、およびブリッジパッケージ用の Python 3.11 以降が必要です。

ブートストラップパッケージを、パッケージマネージャーを1つ選んでインストールします。

# Option A — pip
py -m pip install --upgrade arcgis-mcp-bridge

# Option B — uv
uv pip install --upgrade arcgis-mcp-bridge

次に、ArcGIS Pro の Python 環境をクローンします。

# The final JSON report contains the target `python_exe` path.
py -m arcgis_mcp.setup_env

インストール済みのコンソールコマンドが PATH から利用できる場合、arcgis-mcp-setup は py -m arcgis_mcp.setup_env と同じです。

複数の Python がインストールされた Windows システムでの重要事項： セットアップは、報告された arcgis-mcp-env\python.exe に arcgis-mcp-bridge をインストールするまで完了しません。MCP サーバーの command と ARCPY_PYTHON_PATH の両方に、同じインタープリターを使用してください。これにより、別の Python 環境からパッケージやネイティブ拡張が読み込まれることによるワーカーの失敗を防げます。

完全なセットアップと構成については、05 — インストールを参照してください。

100 個の宣言型ジオプロセシングツール。分離された 2 つのプロセス。1 つのセキュリティ基準。

ArcGIS Pro の ArcPy エンジンを、stdio JSON-RPC 経由で Claude Desktop やその他の MCP ホストに公開する、安全性を重視したローカルファーストの非同期 MCP サーバーです。

技術解説：ArcGIS Pro と ArcPy 向けのセキュアな MCP ブリッジの構築

カタログ	100 個のツール · 10 分野
テスト	単体テスト 86 件 · 86/86 合格 · arcpy はモック
実際のランタイムの証拠	再現可能な ArcGIS Pro MCP スモークベンチマーク
静的解析	Ruff クリーン · Mypy strict クリーン
トランスポート	stdio 上の JSON-RPC 2.0
ライセンス	Apache-2.0

---

arcgis-mcp-bridge を選ぶ理由

機能	arcgis-mcp-bridge	geo2004/MCP-ArcGISPro	nicogis (C#/.NET)
ツール	100	約 15	約 10
依存関係の同期	決定的（uv.lock）	命令型（requirements.txt）	ネイティブ NuGet
トランスポート	stdio JSON-RPC	ファイルベース IPC	名前付きパイプ
セキュリティアーキテクチャ	文書化された PathGuard サンドボックス	指定なし／ホストへのデフォルトアクセス	指定なし／ホストへのデフォルトアクセス
arcpy の分離	2 プロセスアーキテクチャ	単一プロセス実行	アドイン内プロセス実行
CI（オフライン検証）	✅ 対応	❌ 利用不可	❌ 利用不可
ライセンス	Apache-2.0	MIT	MIT

---

注目機能：スケッチ → GIS パイプライン

手描きの区画境界 → 写真 → ジオデータベースのフィーチャクラス。 ORB+RANSAC による画像レジストレーション、HSV によるインクのセグメンテーション、GDB への直接コミット。 手作業でのデジタイズは不要です。

デモは近日公開予定です。 スケッチから GIS へのパイプラインを試すには：

1. 紙にポリゴンを描き、写真を撮ります。
2. Claude に次のように依頼します：「extract_sketch_to_gis を使って、この写真をベースマップに合わせて位置合わせし、結果を GDB にコミットしてください。」
3. フィーチャクラスが ArcGIS Pro に表示されます。手作業でのデジタイズは不要です。

---

00 — プロンプトの例

health_check が成功したら、Claude に自然な言葉で話しかけます。

"Buffer all parcels in my GDB by 50 meters and save to scratch."
"List all feature classes in C:\GIS\city.gdb starting with 'road_'."
"Dissolve the neighborhoods layer by district_id."
"Run kernel density on crime_points with a 500-meter search radius."
"Calculate slope and aspect from the DEM at C:\GIS\dem.tif."
"Find the 3 nearest facilities to each incident in my network dataset."
"Check geometry on all feature classes in my GDB and repair errors."

01 — コアアーキテクチャと設計思想

flowchart TD
    A[Claude Desktop / Cursor] -->|JSON-RPC over stdio| B[Layer A · MCP Protocol Host]
    B -->|NDJSON subprocess bridge| C[Layer B · ArcPy Worker]
    C --> D[ArcGIS Pro / ArcPy Runtime]

レイヤー A — 非同期イベント駆動サーバー（arcgis_mcp/server.py）。 ブリッジインタープリター上で FastMCP を実行します。stdio チャネルを管理し、すべてのリクエストを固定された Pydantic v2 コントラクトに照らして検証し、asyncio.create_subprocess_exec で処理をディスパッチします。イベントループがジオプロセシング呼び出しでブロックされることはなく、スレッドロックを保持することもありません。レイヤー A にはモジュールレベルの arcpy または cv2 のインポートが一切ありません（監査ゲートで grep により検証済み）。Esri のネイティブコードに触れることがないため、それが原因でクラッシュすることはありません。

レイヤー B — サブプロセス ArcPy 分離ワーカー（arcgis_mcp/worker.py）。 ライセンスが付与された ArcGIS Pro インタープリター（ARCPY_PYTHON_PATH）上で、ジョブごとに起動します。import arcpy が許可される唯一の場所です。cv2 は、それを必要とする唯一のビジョンツール内で遅延読み込みされます。起動時にワーカーの標準出力は標準エラーに割り当て直されるため、許可された標準出力への書き込みは最後の NDJSON 結果フレームのみです。したがって、ネイティブ ArcObjects のメッセージが JSON-RPC チャネルを破損させることはありません。ネイティブクラッシュが発生すると、サーバーではなくワーカーが終了します。親プロセスは、ゼロ以外の終了コードを構造化エラーフレームに変換します。

宣言的レジストリ（arcgis_mcp/registry.py）。 各ツールは ToolSpec(name, category, description, input_model, worker_fn, destructive) です。汎用プロキシファクトリーがレイヤー A ですべてのカタログ MCP エンドポイント 100 個を生成し、汎用の run_tool ディスパッチャーがレイヤー B でそれらを提供します。カタログは、3 つのコアエンドポイント health_check、list_layers、execute_spatial_tool とともに公開されます。カタログのツール #101 を追加する場合、変更が必要なのは 2 つのファイルだけで、ランタイムループには手を加えません。

プロセス境界を越えるすべての障害は、次のように分類されます。 validation · security · not_found（入力パスが存在しません。メッセージにはフィールド名とパスが含まれます） · license · geoprocessing（完全な arcpy.GetMessages() スタック、または Describe などのジオプロセシング以外の呼び出しでは ArcPy 独自のメッセージ） · internal（例外の種類とメッセージ。トレースバックはサーバーログに保持されます）。

---

02 — 100 ツールの分野別一覧

#	分野	ツール数	主な機能
1	map_layer_management	10	.aprx のマップ、レイヤーの順序・表示設定・シンボル、カメラ、保存
2	data_management	22	FC/GDB のライフサイクル、フィールド、Describe、Excel/GeoJSON/CSV の交換
3	geometry_analysis	23	オーバーレイ、ディゾルブ／マージ、選択、結合、近接、フィッシュネット
4	coordinate_reference_projection	4	ベクターとラスターの WKID に基づく定義／投影、CRS 検索
5	raster_operations	15	マップ代数、ゾーン統計、DEM の傾斜／方位／陰影起伏図、水文解析
6	vision_analytics	1	スケッチから GIS へ：ORB+RANSAC 登録 → HSV インク → GDB へのコミット
7	export_layout	9	PDF/PNG のプロット、DPI 制御、マップフレーム、テキスト／凡例、ページサイズ
8	editing_topology	7	ジオメトリの修復／チェック、追加、重複排除、差分、トポロジの検証
9	network_analysis	4	サービスエリア、ルート検索、OD コストマトリックス、最寄り施設
10	spatial_statistics	5	平均中心、楕円、カーネル密度、Gi* ホットスポット、Moran's I
	合計	100

Esri の拡張ライセンス（Spatial、Network）は、共有のコンテキストマネージャーで管理し、通常の Python 例外が発生した場合は finally を通じて返却します。ワーカープロセスによる分離で、ネイティブ障害を現在のジョブ内に封じ込めます。ライセンスが利用できない場合は、MCP サーバーを終了させず、構造化エラーフレームを返します。

破壊的な変更に対する安全性の最低基準

状態を変更する10個のツールは、明示的な confirm: true ペイロードトークンがなければ実行を拒否します。このゲートは、10～30秒かかる arcpy のインポートが発生する前にディスパッチャーで作動し、レジストリも、コントラクトに confirm フィールドがない破壊的な仕様の登録を拒否します。

append_features        calculate_field        define_projection
delete_dataset         delete_field           delete_identical
extract_sketch_to_gis  near_analysis          remove_layer_from_map
repair_geometry

calculate_field には、式チャネルに関する追加の最低基準があります。デフォルトの expression_type は ARCADE（Esri のサンドボックス化された式言語）であり、ワーカー内でコードを実行する PYTHON3 は、confirm: true が明示的に指定されない限り、Layer-A コントラクトの境界で拒否されます。raster_calculator の式は、コントラクトバリデーターによって純粋なマップ代数文法（識別子、数値、演算子。引用符や dunder アクセスは不可）に制限されます。

---

03 — 自動品質ゲートとテスト

ライセンスが必要なランタイムのエビデンスは、benchmarks/ の方法カードで別途報告します。コミットされた結果は、実際の ArcGIS Pro ワーカーと専用のスクラッチ GDB を使用しています。モックを使った単体テストの数には合算しておらず、100個すべてのジオプロセシングツールの検証として示しているわけでもありません。

適用範囲を明確にすると、現在の自動ゲートは86件の単体テストで構成されており、PathGuard の境界、Pydantic コントラクト、汎用レジストリのパスガードと登録の不変条件、ワーカーのエラー境界マッピング、Settings の環境変数検証を対象としています。カタログの構造的なコントラクトと、セキュリティ上重要なすべての接点をテストしますが、ライセンスされた ArcGIS ランタイムで実行され、CI ランナーでは利用できない100個のジオプロセシングツールそのものについて、複数シナリオでの検証を行ったとは主張しません。

メモリー内テストアーキテクチャ。 tests/conftest.py は、パッケージのインポートが解決される前に、sys.modules["arcpy"] と sys.modules["arcpy.sa"] に MagicMock プロキシを注入します（CheckExtension は "Available" を返します）。スイート全体は1秒未満で実行され、ローカルと CI のどちらでも ArcGIS のインストール、ライセンスのチェックアウト、Esri ランタイムは不要です。

テストの対象範囲。

• tests/test_security.py と tests/test_pathguard.py — pytest の tmp_path フィクスチャを使い、実際のディレクトリで検証する PathGuard 境界ファイアウォールです。サンドボックス内の有効な読み書きは許可されます。トラバーサル（.. セグメント）、UNC、相対パス、NUL バイト、予約済みデバイス名、長さ超過、ルート外のパスは拒否されます。書き込み規則（ArcGIS データセット名のルール、上書きの明示的な許可）も適用されます。
• tests/test_contracts.py — Pydantic コントラクトの適用をテストします。ツールごとのパラメーター仕様、フィールド間バリデーター、frozen / extra="forbid"、IPC エンベロープの ok と error の排他的な不変条件が対象です。
• tests/test_registry.py と tests/test_registry_guard.py — レジストリストリームの整合性に加え、汎用の apply_path_guard の適用と register の不変条件をテストします。すべてのスキーマは ToolInput のサブクラスであること、すべての path_fields エントリーは有効なロールを参照すること、名前の重複は拒否されること、すべての破壊的な仕様に confirm ゲートが必要であることを検証します。
• tests/test_worker.py — process_frame のエラー境界マッピングをテストします。失敗の各クラス（検証、セキュリティ、ライセンス、ジオプロセシング、内部エラー）が、それぞれ異なる WorkerError.kind にマッピングされます。
• tests/test_config.py — Settings.from_environment の検証をテストします。必須変数、ディレクトリとファイルのチェック、整数の範囲、スクラッチジオデータベースがない場合のフェイルファストが対象です。

レジストリテストの副作用を伴うインポート import arcgis_mcp.tools が、カタログにデータを登録します。このインポートには # noqa が付与されており、リンターによって再び削除されないようになっています。

静的解析。 Ruff は標準的なフォーマットに加え、py311 を下限として、88桁の行幅で E/W/F/I/B/RUF を適用します（コードはサポート対象の最も古いインタープリターで解析できる必要があります。Layer B）。トルコ語のコメントも正式にサポートされています。ドットなしの ı / İ は allowed-confusables に登録されているため、文章は書き換えず、その文字を許容する設定になっています。Mypy は Pydantic プラグインを使い、31個すべてのソースファイルに対して strict = true で実行されます。

make format          # ruff format + import sorting (mutates)
make lint            # ruff check, mutates nothing
make type-check      # mypy --strict over arcgis_mcp/
make security-audit  # live registry inspection: path roles + confirm gates
make verify-all      # lint + type-check + security-audit, one gate
python -m pytest     # 86/86

---

04 — セキュリティフレームワーク（PathGuard サンドボックス）

各コントラクトのすべてのファイルシステム引数では、モデルの path_fields マッピング内で役割（"read"、"write"、"read_list"）を宣言します。共有の適用関数が、両方のプロセスでこれらの宣言を適用します。Layer A はワーカーの起動前に事前チェックを行い、Layer B は親プロセスを決して信頼しないため、再検証を行います。

境界を制御する仕組みは2つあります。

• validate_read(raw: str) — パスを完全に解決し（比較の前にシンボリックリンク、..、相対セグメントをすべて解決します）、設定された allowed_roots ディレクトリ内に含まれていることを要求します。存在確認には、最も深い既存のプレフィックスを解決する方法を用います。対象のパス、またはファイルシステムで解決可能なジオデータベースのプレフィックスが存在しなければなりません。これにより、GDB 内のデータセット（…\city.gdb\roads）を第一級の対象として扱えます。ファイルシステム上で .gdb コンテナーを検証し、論理的な後続部分は、arcpy でのみ解決できるプレーンなデータセット名に制限します。
• validate_write(raw: str, *, overwrite: bool) — 同じ解決と包含確認に加え、ArcGIS で有効なデータセット名と上書きルールを適用します。リクエストで overwrite: true が明示的に指定されていない限り、既存の対象を置き換えることはありません。

トラバーサルシーケンス、UNC 共有、NUL バイト、予約済みデバイス名、許可されたルート外の対象など、あらゆる境界逸脱パターンは、ただちに PathSecurityError を発生させます。そのリクエストには構造化された security フレームが返され、サブプロセスは一切起動されません。

---

05 — 📦 インストール

用途に合った導入方法を選択してください。

前提条件

• ライセンス済みの ArcGIS Pro がインストールされた Windows
• arcgis-mcp-bridge 用の Python 3.11 以降
• ARCGIS_MCP_ALLOWED_ROOTS に指定する、書き込み可能な既存ディレクトリ
• 既存のファイルジオデータベース（<first allowed root>\scratch.gdb がすでに存在する場合を除き、ARCGIS_MCP_SCRATCH_GDB 用）

パス A：PyPI のみでインストール — Windows ユーザーに推奨

これは、Windows 上の Claude Desktop やその他の MCP ホストに最も簡単で信頼性の高いセットアップ方法です。推奨構成では、Layer A（MCP サーバー）と Layer B（ArcPy ワーカー）の両方に、同じ arcgis-mcp-env\python.exe を使用します。

ブートストラップ用のインストールコマンドを1つ選択してください。

# Option A — pip
py -m pip install --upgrade arcgis-mcp-bridge

# Option B — uv
uv pip install --upgrade arcgis-mcp-bridge

次に、ArcGIS Pro の Python 環境をクローンします。

# The final JSON report contains the target `python_exe` path.
py -m arcgis_mcp.setup_env

インストール済みのコンソールコマンドが PATH から利用できる場合、arcgis-mcp-setup は py -m arcgis_mcp.setup_env と同等です。

JSON レポートから python_exe の値をコピーし、以下に割り当てます。

$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"

インストールコマンドを1つ選択してください。

# Standard installation
& $ArcGISMcpPython -m pip install --upgrade arcgis-mcp-bridge

# OR: include the optional OpenCV-based sketch-to-GIS extension
& $ArcGISMcpPython -m pip install --upgrade "arcgis-mcp-bridge[vision]"

両方のコマンドを実行しないでください。2つ目のコマンドは、標準パッケージと vision エクストラをすでにまとめてインストールします。

$ArcGISMcpPython を MCP サーバーのインタープリターと ARCPY_PYTHON_PATH の両方に使用してください。これにより、arcgis_mcp、Pydantic、pydantic-core、その他のネイティブ依存関係が、別の Python インストールから解決されるのを防ぎます。

パス B：Git クローンと決定論的な開発 — GIS のコントリビューター向け

この方法では、Layer A を隔離された開発環境に保ちながら、ArcPy の処理は別途クローンしたライセンス済みの arcgis-mcp-env ワーカーで実行します。

# 1. Clone the repository.
git clone https://github.com/muend/arcgis-mcp-bridge.git
cd arcgis-mcp-bridge

# 2. Create the isolated development environment.
#    Do not use --system-site-packages: Layer A must remain independent of arcpy.
uv venv --python "C:\Program Files\ArcGIS\Pro\bin\Python\envs\arcgispro-py3\python.exe"

# 3. Synchronize the committed dependency resolution.
uv sync --locked

ワーカーのプロビジョニングコマンドを1つ選択してください。

# Standard worker
uv run python -m arcgis_mcp.setup_env --install-runtime-deps --project-root .

# OR: worker with the optional OpenCV-based sketch-to-GIS extension
uv run python -m arcgis_mcp.setup_env --with-vision --project-root .

--with-vision はランタイム依存関係のインストールも行うため、2つのコマンドを続けて実行しないでください。

セットアップコマンドは冪等で、--env-name（デフォルト：arcgis-mcp-env）と --dry-run を受け付け、JSON レポートを出力します。ArcGIS Pro の conda.exe が PATH から利用できない場合は、ARCGIS_CONDA_EXE を設定してください。

ワーカーインタープリターの整合性

レイヤー B は次のように起動します。

ARCPY_PYTHON_PATH -m arcgis_mcp.worker

ARCPY_PYTHON_PATH で指定されたインタープリターは、ワーカースタック全体をインポートできる必要があります。

arcgis_mcp
pydantic
pydantic_core
arcpy

Windows に初めてインストールする場合は、サーバーの command と ARCPY_PYTHON_PATH に同じ arcgis-mcp-env\python.exe を使用してください。開発時はサーバー環境とワーカー環境を分ける構成も引き続きサポートされますが、ワーカーのインタープリターには、互換性のある独自の arcgis-mcp-bridge とすべての実行時依存関係をインストールする必要があります。

MCP ホストを設定する前に、この事前チェックを実行してください。

$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"

& $ArcGISMcpPython -c "import sys, arcgis_mcp, pydantic, pydantic_core; print(sys.executable); print('Bridge runtime OK')"
& $ArcGISMcpPython -c "import arcpy; print('ArcPy', arcpy.GetInstallInfo().get('Version'))"

環境変数

変数	必須	用途
ARCPY_PYTHON_PATH	はい	ライセンスが有効なワーカーの python.exe への絶対パスです。arcgis_mcp、Pydantic／pydantic_core、ArcPy を解決できる必要があります
ARCGIS_MCP_ALLOWED_ROOTS	いいえ	Windows で ; 区切りの PathGuard 境界ルートです。既定値は ~/Documents/ArcGIS/Projects です
ARCGIS_MCP_SCRATCH_GDB	いいえ	既定の出力ワークスペースです。省略した場合、既定値は <first allowed root>\scratch.gdb です。GDB は事前に存在している必要があります
ARCGIS_MCP_LOG_FILE	いいえ	ローテーションされるログファイルの任意のパスです
ARCGIS_MCP_LOG_LEVEL	いいえ	DEBUG、INFO、WARNING、ERROR のいずれかです。既定値は INFO です
ARCGIS_MCP_TOOL_TIMEOUT	いいえ	ジョブごとの正のタイムアウト秒数です。既定値は 600 です
ARCGIS_MCP_MAX_WORKERS	いいえ	ArcPy ワーカーの同時実行数の上限です。既定値は 2 で、ライセンス枠と RAM を保護します

Claude Desktop の設定

ARCPY_PYTHON_PATH はすべての設定で必須であり、セットアップコマンドで報告された、ライセンスが有効なインタープリターを指定する必要があります。

以下のすべてのプレースホルダーのパスを、お使いのマシンに存在するパスに置き換えてください。スクラッチジオデータベースは事前に存在している必要があります。

オプション 1：統合 PyPI 環境 — Windows で推奨

MCP サーバーと ArcPy ワーカーに同じインタープリターを使用します。

{
  "mcpServers": {
    "arcgis-mcp-bridge": {
      "command": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
      "args": [
        "-m",
        "arcgis_mcp.server"
      ],
      "env": {
        "ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
        "ARCGIS_MCP_ALLOWED_ROOTS": "C:\\GIS\\Data;C:\\Workspace",
        "ARCGIS_MCP_SCRATCH_GDB": "C:\\GIS\\Data\\scratch.gdb",
        "ARCGIS_MCP_MAX_WORKERS": "2"
      }
    }
  }
}

この設定では、command と ARCPY_PYTHON_PATH の値を同じにしてください。セットアップコマンドで返された python_exe の値を使用します。

オプション 2：ローカル Git 開発環境

レイヤー A にはリポジトリの .venv を、レイヤー B にはプロビジョニング済みの arcgis-mcp-env を使用します。

{
  "mcpServers": {
    "arcgis-mcp-bridge": {
      "command": "C:\\path\\to\\arcgis-mcp-bridge\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "arcgis_mcp.server"
      ],
      "env": {
        "ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe",
        "ARCGIS_MCP_ALLOWED_ROOTS": "C:\\GIS\\Data;C:\\Workspace",
        "ARCGIS_MCP_SCRATCH_GDB": "C:\\GIS\\Data\\scratch.gdb",
        "ARCGIS_MCP_MAX_WORKERS": "2"
      }
    }
  }
}

この環境分割の設定では、上記の Path B のセットアップコマンドのいずれかを使って、リポジトリからワーカーがプロビジョニングされていることを前提とします。uv sync --locked によってプロジェクトがリポジトリの .venv にインストールされている場合、PYTHONPATH は不要です。

グローバルに解決される arcgis-mcp-server コマンドも動作する場合がありますが、環境分割のデプロイになります。ワーカー環境を別途プロビジョニングして検証していない限り、Windows への初回セットアップには推奨されません。

MCP ホストを再起動したら、まず health_check を呼び出してください。これにより、サーバーとワーカー間の IPC 経路が検証され、ArcPy をインポートせずに選択されたワーカーインタープリターが報告されます。その後、読み取り専用の ArcGIS ツールを実行するか、上記の ArcPy 事前チェックコマンドを実行して、ライセンスが有効なランタイムを検証してください。

---

06 — トラブルシューティング

Worker process exited with code 1

MCP サーバーは起動するものの、すべての ArcGIS ツールが失敗する場合は、サーバーログでワーカーのトレースバックを確認してください。環境に関連する一般的な原因は次のとおりです。

ModuleNotFoundError: No module named 'arcgis_mcp'
ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'

これらのエラーは通常、ワーカーが別の Python インストールを使用している、ブリッジがワーカーのインタープリターにインストールされていない、またはワーカーに不完全もしくは互換性のない Pydantic がインストールされていることを意味します。推奨される解決方法は、上記で説明した統一環境の設定です。

推奨される統一設定では、2 つの値が同一であることを確認してください。

"command": "C:\\...\\envs\\arcgis-mcp-env\\python.exe"

"ARCPY_PYTHON_PATH": "C:\\...\\envs\\arcgis-mcp-env\\python.exe"

その同じインタープリター内でブリッジをインストールまたは更新します。

$ArcGISMcpPython = "C:\...\envs\arcgis-mcp-env\python.exe"
& $ArcGISMcpPython -m pip install --upgrade arcgis-mcp-bridge

選択された実行ファイルとブリッジの依存関係を確認します。

& $ArcGISMcpPython -c "import sys, arcgis_mcp, pydantic, pydantic_core; print(sys.executable); print('Bridge runtime OK')"

次に、ArcPy を個別に確認します。

& $ArcGISMcpPython -c "import arcpy; print('ArcPy', arcpy.GetInstallInfo().get('Version'))"

ブリッジの検証が pydantic_core 内で引き続き失敗する場合は、pip が一致するコンパイル済み依存関係を復元できるよう、同じ環境で Pydantic を再インストールします。

& $ArcGISMcpPython -m pip install --upgrade --force-reinstall --no-cache-dir "pydantic>=2.5,<3"

Python 環境または設定を変更した後は、MCP ホストを完全に再起動してください。

ARCPY_PYTHON_PATH が間違った実行ファイルを指している

Windows の conda 環境では、通常、インタープリターは環境のルートにあります。

C:\...\envs\arcgis-mcp-env\python.exe

別のグローバル Python インストールや、存在しない arcgis-mcp-env\Scripts\python.exe のパスは使用しないでください。

スクラッチ ジオデータベースの起動エラー

デフォルトのスクラッチ ワークスペースは次のとおりです。

<first allowed root>\scratch.gdb

あらかじめ作成されている必要があります。ArcGIS Pro で作成するか、MCP ホストを再起動する前に ARCGIS_MCP_SCRATCH_GDB を既存のファイル ジオデータベースに設定してください。

health_check は成功するが ArcGIS ツールは失敗する

health_check は、ArcPy をインポートせずにサーバーとワーカーのプロセス境界を確認するよう設計されています。成功した結果は IPC とインタープリターの選択が機能していることを示しますが、ArcPy やオプションの Esri 拡張ライセンスが読み込めることを証明するものではありません。

上記の ArcPy プリフライト コマンドを実行し、not_found、license、geoprocessing、または internal の詳細について、構造化されたワーカーエラーを確認してください。

最初の ArcGIS ツール呼び出しがタイムアウトする

各ツール呼び出しでは、ArcPy をインポートする新しいワーカーが起動します。通常は 10～30 秒かかりますが、リアルタイムのウイルス対策スキャンが ArcGIS Pro のネイティブ DLL をスキャンするマシンでは、初回のインポートに約 230 秒かかったことがあります。DLL がキャッシュされた後の呼び出しは高速です。このようなマシンでは、ARCGIS_MCP_TOOL_TIMEOUT をデフォルトの 600 秒以上に設定してください。ArcGIS Pro のインストールをリアルタイムスキャンから除外するかどうかは、そのマシンの管理者が決定するセキュリティ上の判断です。

import_from_geojson とジオメトリタイプ

ArcPy の JSONToFeatures は、別途指定されない限り、.geojson ファイルをポリゴンとして読み込み、他のジオメトリを黙って破棄します。そのため、ブリッジはファイルからジオメトリタイプを検出し、明示的に渡します。ポイント、ライン、ポリゴンが混在するファイルはタイプごとの件数とともに拒否されます。geometry_type を設定して、タイプごとにインポートしてください。フィーチャが 0 件になるインポートは、空のフィーチャクラスを返すのではなく、明示的に失敗します。

---

07 — 互換性

ArcGIS Pro	同梱 Python	ステータス
3.3	3.11	✅ 参照プラットフォーム
3.4	3.11	⚠ コミュニティからの報告あり。プリフライトチェックで確認してください
3.6	3.13	✅ コミュニティで検証済み：全テストスイートとランタイムベンチマーク（#24）
3.7	3.13	✅ メンテナーによるランタイムベンチマーク検証済み（結果）
3.1–3.2	3.9	❌ 現在の Python >=3.11 パッケージ要件ではサポートされていません

Windows のみ。 ArcPy の実行には、Windows 上のライセンス済み ArcGIS Pro インストールが必要です。 レイヤー A は開発やモック CI のために他のプラットフォームでも実行できますが、レイヤー B には ArcGIS Pro が必要です。

ブリッジパッケージ自体には Python 3.11 以降が必要です。クローンした Python 環境が 3.11 より古い ArcGIS Pro リリースでは、現在のワーカーパッケージを実行できません。

---

08 — ライセンス

Apache License 2.0。LICENSE を参照してください。