Arcgis Portal Mcp

arcgis-portal-mcp

v1.15.0。 为 ArcGIS Enterprise Portal 和 ArcGIS Online 提供 81 个工具。

一个模型上下文协议（MCP）服务，让 AI 助手可以直接访问你的 ArcGIS 内容。通过自然语言搜索、检查、编辑、发布和管理内容。

适用于 Claude Desktop、Cursor、VS Code Copilot 以及任何兼容 MCP 的客户端。

免责声明： 这是一个独立的开源项目，与 Esri 无关，也未获得 Esri 的认可或赞助。“ArcGIS”是 Esri 的注册商标。

v1.14.0 有哪些新功能

• 修复了 ArcGIS Enterprise 12.x 的发布问题：upload_item 现在使用正确的 /addItem 端点，而 publish_from_item 会发送 ArcGIS 预期的确切线路格式（fileType、小写的 itemid，以及发布 URL 中的用户 GUID）。在 Enterprise 12.x 上，旧代码会返回“成功”，但 ArcGIS Server 实际上并未创建托管服务。
• CSV 发布开箱即用：发布 CSV 时，即使不提供 layerInfo，也会根据表头和首行数据自动生成字段架构，包括检测经纬度坐标。缺少该信息时，ArcGIS 会悄无声息地导致 CSV 发布失败。

v1.13.0 有哪些新功能

• 修复 Enterprise 搜索问题：search_items("*") 现在可在 Enterprise 门户上正常运行。当字面值 * 返回 0 个项目时，会自动改用基于访问权限的查询。
• 系统内容过滤：portal_inventory 默认会排除 Esri 系统账户（esri_*、portaladmin），从而准确统计组织的实际内容。传入 exclude_system_content=false 可包含系统内容。

v1.12.0 有哪些新功能

• portal_inventory：扫描门户内容，并按类型、所有者、时间和存储空间统计项目数量。全面了解组织的内容。
• bulk_reassign_ownership：批量转移用户之间的内容所有权。对于员工离职和团队调整至关重要。
• `offboard_user：通过转移用户的内容并将其移出群组来办理用户离职。
• AGOL 修复：portal_inventory 现在可以正确查询 ArcGIS Online 组织（此前会返回 0 个项目）。
• 可靠的自动连接：始终从 .env 重新读取凭据，修复网关重启后的身份验证信息过期问题。

v1.11.1 有哪些新功能

• 修复 Enterprise 搜索问题：search_items("*") 现在可在需要 contentStatus=all 的 Enterprise 门户上正常运行。
• 自动重新连接：长时间操作期间令牌过期（例如扫描过期内容、损坏的引用）时，会自动重新进行身份验证。
• 加快损坏引用扫描：使用 HEAD 请求代替 GET；遇到 405 时回退。
• 改进错误诊断：admin_request 错误包含 http_status 代码；server_status 显示身份验证方式和令牌过期时间。
• 优化 find_stale_items：仅对已判定为过期的项目获取完整详情，以进行治理检查。
• 统一字段命名：统一使用 full_name（get_user_details 中原为 fullname）。
• portal_health 现在会显示 portal_url 和 connected_as。
• search_content 的默认 max_items 从 20 提高到 100。
• list_users 除格式化日期外，还会提供 last_login_epoch（原始毫秒值）。

v1.11.0 有哪些新功能

• 损坏引用扫描器：扫描 Web 地图、仪表板和应用，查找无法访问的服务 URL。在用户报告之前发现损坏的图层。
• 过期内容查找器：识别 N 天内未修改的项目，并检测治理违规。清理门户中的冗余内容。
• 导出群组内容：将群组项目导出为 Enterprise .epk 包，以便在门户之间迁移内容。
• 导入群组内容：将 .epk 包中的项目导入目标群组。

v1.10.0 有哪些新功能

• 群组生命周期管理：更新、删除群组并管理群组成员——完成门户群组的 CRUD 流程。
• 删除文件夹：移除内容文件夹（并提示其中包含的内容）。
• 搜索用户：按姓名、电子邮件或用户名查找用户，无需导出完整用户列表。

v1.9.0 有哪些新变化

• 只读模式：通过 MCP_READ_ONLY=true 或 --read-only CLI 标志，禁止所有写入/修改工具
• 工具允许列表：通过 MCP_ALLOWED_TOOLS=name1,name2 限制 AI 客户端可以查看和调用的工具
• 审计日志：通过 MCP_AUDIT_LOG=path 将每次工具调用记录到 JSONL 文件，并自动清除密码和令牌

v1.8.0 有哪些新变化

• 协作：列出、检查分布式 GIS 协作，并触发同步
• 角色和权限：列出组织角色及其完整权限集
• 计划任务：列出并筛选组织级或用户级计划任务

v1.7.0 有哪些新变化

• Webhook：列出、创建、更新、删除和测试组织 Webhook，实现门户自动化
• 日志：按级别/来源/时间筛选条件查询和清理门户日志
• 组织设置：读取和更新门户配置
• 文件夹：创建和列出内容文件夹，以便更好地整理项目

v1.6.0 有哪些新变化

• 可配置的 TLS 验证：默认启用证书验证；对于自签名 Enterprise 证书，请设置 MCP_TLS_VERIFY=false
• 范围限定的允许列表：通过 MCP_ALLOWED_* 环境变量，限制服务可访问的门户、所有者、群组和服务 URL

安全改进的灵感来自 Esri Community 上 muend 的社区反馈。

v1.5.0 有哪些新变化

• 项目影响分析：了解删除项目会导致哪些内容失效。
• 关系浏览器：映射服务、Web 地图、图层和应用。
• 使用情况分析：API 调用、活跃用户、存储趋势（管理员）。
• 群组成员审计：了解用户所属的群组以及非活跃用户。
• 服务依赖扫描器：查找失效链接和缺失的数据源。
• 批量操作：一次更新、共享或删除多个项目。

功能

• 连接到任意 ArcGIS Enterprise Portal 或 ArcGIS Online。
• 搜索项目：要素服务、Web 地图、图层、仪表板。
• 检查项目元数据、标签和描述。
• 描述图层：完整架构，包括字段、域、子类型、关系和渲染器信息。
• 查询要素，支持属性筛选、空间筛选、字段选择和分页。
• 添加、更新和删除要素，适用于托管要素图层。
• 管理内容：更新属性、共享/取消共享、删除项目、读取 Web 地图定义。
• 管理用户：列出用户、获取详细个人资料。
• 管理群组：列出群组、创建群组并邀请用户。
• 发布服务：上传文件并发布为托管要素服务。
• 检查 GP 工具：列出任务并在执行前查看参数架构。
• 运行地理处理：执行同步和异步 GP 任务。
• 导出地图图像：将图层渲染为 JPG/PNG/GIF/PDF/SVG。
• 门户管理：系统信息、许可证管理、使用统计。
• 批量操作：批量删除、共享和更新多个项目。
• 运行状况检查：门户系统状态（需要管理员权限）。

设计原则

• 不依赖 arcgis Python 包：通过 requests 调用原始 REST API，无需再费力处理 Esri 的 Python SDK。
• 同时适用于 Enterprise Portal 和 ArcGIS Online：工具相同，API 相同。
• 支持多种身份验证方式：token、用户名/密码、client_credentials 和 OAuth2。
• 自动连接：启动时读取 .env 文件，无需在每个会话中手动进行身份验证。
• 兼容双重身份验证：适用于要求双重身份验证的 Enterprise 门户。
• 兼容自签名证书：支持使用自签名证书的 Enterprise 门户。
• 安全加固：对 WHERE 子句进行 SQL 注入验证，在 OAuth 回调中防止 XSS，自动使用指数退避重试，支持只读模式、工具允许列表和审计日志。
• 范围限定的允许列表：可选择限制服务可访问的门户、所有者、群组和服务 URL，降低生产环境中 Agent 的影响范围。

安装

pip install git+https://github.com/Asem-D/arcgis-portal-mcp.git

或者克隆源代码并安装：

git clone https://github.com/Asem-D/arcgis-portal-mcp.git
cd arcgis-portal-mcp
pip install -e .

Windows 用户：pywin32 会作为平台专用依赖自动安装。

配置

.env 文件（推荐）

创建 .env 文件，以便在启动时自动连接。项目提供了模板：

cp .env.example .env
# Edit .env with your portal credentials

portal_url=https://gis.example.com/portal
# Option 1: Username/password (recommended for most users)
username=your-portal-username
password=your-portal-password
# Option 2: OAuth2 app credentials (app-level, limited permissions)
# oauth_client_id=your-oauth-app-client-id
# oauth_client_secret=your-oauth-app-client-secret

服务会按以下顺序查找 .env：

1. 软件包目录（与服务代码位于同一目录）——适用于从源代码安装
2. 当前工作目录——适用于从项目根目录启动
3. ~/.arcgis-portal-mcp/.env——适用于通过 pip install 安装的用户

支持带引号的值：password="my secret"。现有的操作系统环境变量优先于 .env 中的值。

服务会在启动时读取 .env 并自动连接。如果提供了 username 和 password，则使用 generateToken（用户级别，拥有完整权限）。否则，会回退到 client_credentials（应用级别，权限有限）。无需手动调用 connect_portal。

注意：.env 文件已加入 gitignore。切勿提交凭据。.env.example 可以安全提交。

MCP 客户端配置

对于 MCP 客户端（Claude Desktop、Cursor 等），最简单的设置方式是使用 .env 文件：

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "cwd": "/path/to/arcgis-portal-mcp"
    }
  }
}

服务会从 .env 自动连接（在软件包目录、CWD 或 ~/.arcgis-portal-mcp/ 中查找）。MCP 配置中无需设置环境变量。

也可以通过 MCP 客户端环境变量传递凭据：

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "env": {
        "portal_url": "https://gis.example.com/portal",
        "username": "your-portal-username",
        "password": "your-portal-password"
      }
    }
  }
}

连接 MCP 客户端

热门 AI 编码助手的分步设置说明。

Claude Desktop

1. 安装 arcgis-portal-mcp（参见安装）
2. 创建 ~/.arcgis-portal-mcp/.env 并填入凭据
3. 打开 Claude Desktop 设置（Claude 菜单 > 设置 > 开发者 > 编辑配置）
4. 将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "cwd": "/path/to/arcgis-portal-mcp"
    }
  }
}

5. 重启 Claude Desktop。服务会从 .env 自动连接。

**macOS/Linux：**如果需要，将 python 替换为 python3。使用 which python3 查找完整路径。

Cursor

1. 安装 arcgis-portal-mcp（参见安装）
2. 创建 ~/.arcgis-portal-mcp/.env 并填入凭据
3. 打开 Cursor 设置（齿轮图标 > MCP）
4. 点击“Add new global server”并粘贴以下内容：

{
  "name": "arcgis-portal",
  "command": "python",
  "args": ["-m", "arcgis_portal_mcp.server"],
  "cwd": "/path/to/arcgis-portal-mcp"
}

5. 启用该服务。Cursor 会自动连接。

VS Code（GitHub Copilot）

1. 安装 arcgis-portal-mcp（参见安装）
2. 创建 ~/.arcgis-portal-mcp/.env 并填入凭据
3. 将以下内容添加到工作区中的 .vscode/mcp.json（或用户设置）：

{
  "servers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "cwd": "/path/to/arcgis-portal-mcp"
    }
  }
}

4. 重新加载 VS Code。MCP 服务会显示在 Copilot 聊天面板中。

Windsurf

1. 安装 arcgis-portal-mcp（参见安装）
2. 创建 ~/.arcgis-portal-mcp/.env 并填入凭据
3. 打开 Windsurf 设置 > Cascade > MCP Servers
4. 添加新服务：

{
  "name": "arcgis-portal",
  "command": "python",
  "args": ["-m", "arcgis_portal_mcp.server"],
  "cwd": "/path/to/arcgis-portal-mcp"
}

5. 重启 Windsurf。

nanobot（此 Agent）

已配置完成。MCP 服务已在 config.json 的 tools.mcpServers.arcgis-portal 下注册。

connect_portal 工具参数

connect_portal 工具接受以下 auth_method 值：

值	行为
auto	从 .env 读取（默认）。先尝试用户名/密码，再尝试 client_credentials
username_password	门户用户名 + 密码 -> generateToken（用户级）
token	使用显式指定的门户令牌
client_credentials	使用显式指定的 client_id/secret
oauth2	基于浏览器的 OAuth2（阻塞约 2 分钟）

用法

连接并搜索

User: Search for all feature services in my portal
Agent: [calls connect_portal, then search_content with item_type="Feature Service"]

检查图层的完整架构

User: Show me the field schema of the infrastructure layer
Agent: [calls list_layers to find the layer, then describe_layer to get fields, domains, relationships]

查询图层

User: Show me the first 10 parcels from the cadastral layer
Agent: [calls list_layers to find the parcel layer, then query_features with limit=10]

运行前检查 GP 工具

User: What parameters does the buffer analysis tool expect?
Agent: [calls get_gp_task_info with the GP service URL to inspect parameter schemas]

添加要素

User: Add these 3 buildings to the infrastructure layer
Agent: [calls add_features with the feature service URL and JSON features]

共享 Web 地图

User: Share item abc123 with the "Planning Team" group and the whole org
Agent: [calls share_item with org=true and groups=<planning-team-id>]

读取 Web 地图

User: What basemap and layers are in this web map?
Agent: [calls get_item_data to read the web map JSON, summarizes basemap and operational layers]

发布 Shapefile

User: Publish this shapefile as a hosted feature service
Agent: [calls upload_item to upload the .zip, then publish_from_item to create the service]

运行地理处理任务

User: Run the buffer analysis on the parcels layer with a 100m distance
Agent: [calls get_gp_task_info to inspect parameters, then execute_gp_task with the right inputs]

批量操作

User: Delete all my draft items
Agent: [calls search_content to find items, then batch_delete_items to remove them]

门户管理

User: How many licenses do we have left?
Agent: [calls list_licenses to show license allocation and usage]

扫描失效引用

User: Check if any layers in my web map are broken
Agent: [calls scan_broken_references with the web map item ID]

查找过时内容

User: Show me items nobody has touched in over a year
Agent: [calls find_stale_items with days_threshold=365]

可用工具（81 个）

发现与检查

工具	描述
connect_portal	使用门户进行身份验证（auto、token、username/password、client_credentials 或 OAuth2）
search_content	按关键字、类型和所有者搜索项目
get_item_details	获取特定项目的详细元数据
list_layers	列出要素/地图服务中的图层及其几何类型和数量
describe_layer	获取完整图层架构：字段、类型、域、子类型、关系、范围、渲染器
query_features	使用属性/空间过滤器、分页和不同值查询要素
list_users	列出门户用户及其角色和状态
list_groups	列出门户群组及其访问级别
portal_health	检查门户运行状况和系统状态
server_status	检查 MCP 服务连接状态
search_users	按姓名、电子邮件或用户名搜索门户用户
check_service_health	Ping 服务端点并返回状态、延迟、版本和功能
get_item_thumbnail	将项目缩略图下载到本地文件

要素 CRUD、用户/群组和内容管理

工具	描述
add_features	向托管要素图层添加新要素
update_features	更新现有要素（按 OBJECTID）
delete_features	按 OBJECTID 或 WHERE 子句删除要素
apply_edits_batch	在一个原子事务中应用添加、更新和删除操作
get_user_details	获取详细用户资料（角色、权限、存储空间、上次登录时间）
create_group	创建具有访问控制的新群组
update_group	更新群组属性（标题、描述、可见性）
delete_group	从门户删除群组
list_group_users	列出特定群组中的用户
invite_to_group	邀请用户加入群组并分配角色
remove_from_group	从群组中移除用户
update_item	更新项目属性（标题、描述、标签、访问权限、accessInformation、licenseInfo）
delete_item	从门户删除项目
share_item	与所有人、组织或特定群组共享/取消共享项目
get_item_data	读取项目数据（Web 地图 JSON、应用配置、要素集合）
create_folder	创建内容文件夹以整理项目
list_folders	列出用户的内容文件夹
delete_folder	删除内容文件夹（及其中的所有项目）
clone_item	在同一门户中克隆项目
move_items	在门户用户之间重新分配项目所有权

发布、地理处理、管理和批处理

工具	描述
upload_item	将本地文件（CSV、Shapefile 等）上传到门户内容
publish_from_item	将已上传的项目发布为托管要素服务（未提供 layerInfo 时会自动生成 CSV 图层信息）
create_service	创建带架构的空托管要素服务
get_gp_task_info	检查 GP 工具架构：列出任务，或在执行前查看参数定义
execute_gp_task	运行同步地理处理任务
submit_gp_job	提交异步 GP 作业并获取用于轮询的作业 ID
get_gp_job_status	检查正在运行的异步地理处理作业状态
export_map_image	将 MapServer/FeatureServer 图层导出为 JPG/PNG/GIF/PDF/SVG
portal_system_info	获取门户版本、平台和系统信息（管理员）
list_licenses	获取许可证信息和分配情况（管理员）
portal_usage	获取门户使用统计信息：用户、API 调用、存储（管理员）
get_org_settings	获取组织设置（管理员）
update_org_settings	更新组织设置（管理员）
batch_delete_items	一次删除多个项目
batch_share_items	与相同受众批量共享或取消共享多个项目
batch_update_items	一次更新多个项目的属性
explore_item_relationships	探索项目关系：服务、Web 地图、图层、应用
audit_group_members	审计群组成员身份：哪些用户属于哪些群组、非活跃用户
scan_service_dependencies	扫描要素服务依赖项：失效链接、缺失数据源
analyze_item_impact	分析项目影响：删除项目会导致哪些内容失效
get_usage_analytics	获取门户使用分析数据：API 调用、活跃用户、存储趋势
portal_inventory	扫描门户内容：按类型、所有者、时间和存储量统计项目数量
bulk_reassign_ownership	在用户之间批量转移内容所有权
offboard_user	办理用户离职：转移内容、将其从群组中移除

Webhook 和日志（v1.7.0）

工具	描述
list_webhooks	列出组织中的所有 Webhook
create_webhook	创建带有事件触发器的新组织 Webhook
update_webhook	更新 Webhook 属性（名称、URL、触发器、启用状态）
delete_webhook	按 ID 删除 Webhook
test_webhook	发送测试负载以验证 Webhook 连通性
query_logs	按级别、来源和时间筛选条件查询门户日志
clean_logs	删除指定时间之前的门户日志

协作、角色和计划任务（v1.8.0）

工具	描述
list_collaborations	列出门户参与的所有协作
get_collaboration	获取特定协作的详细信息
sync_collaboration	触发协作工作空间同步
list_roles	列出组织中的所有角色及其权限
get_role_privileges	获取特定角色的权限
list_scheduled_tasks	列出组织中的所有计划任务（管理员）
get_user_scheduled_tasks	列出特定用户的计划任务

管理问题解决工具（v1.11.0）

工具	描述
scan_broken_references	扫描 Web 地图/应用中的不可访问服务 URL（项目或群组级别）
find_stale_items	查找 N 天内未修改的项目，并检测治理违规
export_group_content	将群组项目导出到 .epk 包，以便迁移内容（仅限 Enterprise）
import_group_content	将 .epk 包中的项目导入目标群组（仅限 Enterprise）

服务器管理（v1.15.0，仅限 Enterprise）

工具	描述
list_server_services	按文件夹列出托管服务器上的服务及其状态
get_service_details	获取服务的完整管理配置（状态、实例、功能）
start_service	启动托管服务器上已停止的服务
stop_service	停止服务（具有破坏性，要求 confirm=true）
list_server_machines	列出托管服务器站点中的机器及其角色和状态
list_data_stores	列出已注册的数据存储（数据库、文件夹、云存储）

身份验证方式

方式	优点	缺点
自动（默认）	零配置，启动时读取 .env	若无用户名/密码，则回退到应用级身份验证
用户名/密码	通过 generateToken 获取用户级权限	令牌 2 小时后过期；双重身份验证会阻止此方式
令牌	快速，无依赖项	令牌会过期，必须单独获取
客户端凭据	无需浏览器，无需双重身份验证	仅应用级（无用户身份）
OAuth2	完整的用户权限，令牌有效期为 14 天	会打开浏览器，等待约 2 分钟

启用了双重身份验证的 Enterprise 门户： 使用 auto（在 .env 中设置 client_credentials）。令牌身份验证不可用，因为双重身份验证会阻止令牌生成。client_credentials 流程使用应用级 OAuth2，无需浏览器、双重身份验证或用户交互。

ArcGIS Online 或未启用双重身份验证的门户： 对 MCP 来说，通过 generateToken 使用用户名/密码身份验证是最快的方式。在 .env 文件中填写 username 和 password，即可在启动时自动连接。

完整的用户权限： 使用一次 OAuth2 获取长期有效的令牌，然后直接传入该令牌。

安全性

TLS 证书验证

默认情况下，TLS 证书验证处于启用状态。对于使用自签名证书的 Enterprise 门户，可在 .env 中禁用验证：

MCP_TLS_VERIFY=false

禁用验证时，服务器会记录一条警告。对于使用有效证书的生产部署，请重新启用验证。

限定范围的允许列表

在生产环境中，将服务器限制为指定的门户、所有者、群组和服务端点。所有允许列表均为可选；未设置时，服务器不受限制运行（向后兼容）。

# Only connect to these portals
MCP_ALLOWED_PORTAL_URLS=https://gis.example.com/portal

# Only access items owned by these users
MCP_ALLOWED_OWNERS=jsmith,mgarcia,admin

# Only share with these group IDs
MCP_ALLOWED_GROUPS=abc123,def456

# Only operate on services at these URL prefixes
MCP_ALLOWED_SERVICE_URLS=https://gis.example.com/portal/sharing/rest/services

针对允许列表之外资源的操作会被拒绝，并显示明确的错误消息。对于批量操作，所有者允许列表之外的项目会被跳过，并逐项报告。

只读模式（v1.9.0）

在服务器端阻止所有写入/修改类工具。适用于评估、演示以及要求 AI 只能读取数据的环境。

# Via environment variable
MCP_READ_ONLY=true

# Or via CLI flag (overrides env var)
python -m arcgis_portal_mcp.server --read-only

启用后，任何创建、更新或删除门户内容的工具都会被拒绝，并显示明确的错误消息。只读工具（搜索、查询、列出、描述）仍可正常使用。

工具允许列表（v1.9.0）

限制 AI 客户端可查看和调用的工具。设置后，仅通过 MCP 协议公开指定的工具。

# Only expose these 5 tools to the AI
MCP_ALLOWED_TOOLS=search_content,query_features,list_layers,describe_layer,portal_health

未设置时（默认），全部 81 个工具均可用。未列出的工具对 AI 客户端不可见，直接调用时也会被拒绝。

审计日志（v1.9.0）

将每次工具调用记录到 JSONL 文件中，以供安全审查和合规检查。

# Log all tool calls to this file
MCP_AUDIT_LOG=/path/to/audit.jsonl

每条记录包含：

{"ts": 1723500000.0, "tool": "search_content", "args": {"query": "parcels"}, "status": "ok", "duration_ms": 142.3}

敏感参数（password、token、client_secret、secret）会在日志中自动替换为 ***。

接下来

以下是我们正在为后续版本开发的内容：

v2.0.0 — 要素服务同步

• createReplica / sync：离线工作流和双向数据同步
• 项目关联关系 CRUD：添加/移除项目依赖项
• AI 服务管理：启用/禁用 AI 助手（Enterprise 12.0+）

v2.1.0 — 服务基础设施

• 服务联合：列出、验证、联合和取消联合服务
• 机器监控：列出机器和部署状态
• SSL 证书管理：列出、导入、生成

如果这些功能中的任何一项能解决你遇到的问题，请提交问题告诉我们。我们会根据实际需求确定优先级。

开发

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check arcgis_portal_mcp/

许可证

MIT。请参阅 LICENSE。

作者

Asem Daaboul ([email protected])