内容
# arcgis-portal-mcp
ArcGIS Portal 和 ArcGIS Online 的 MCP 服务器。允许 AI 助手搜索内容、查询要素图层、管理要素、处理内容操作以及管理用户和组。
基于 [模型上下文协议](https://modelcontextprotocol.io) 构建，以便与 Claude Desktop、Cursor、VS Code Copilot 等其他 MCP 客户端集成。
> **免责声明：** 本项目是一个独立的开源项目。它与 Esri Inc. 无关，也未得到 Esri Inc. 的认可或赞助。"ArcGIS" 是 Esri Inc. 的注册商标。
## 功能
- **连接** 到任何 ArcGIS Enterprise Portal 或 ArcGIS Online
- **搜索** 项目（要素服务、网络地图、图层、仪表盘）
- **检查** 项目元数据、标签和描述
- **列出图层** 在要素服务中，包含几何类型和计数
- **查询要素** 使用属性过滤器、空间过滤器、字段选择和分页
- **添加、更新和删除要素** 在托管要素图层中
- **管理内容**：更新项目属性、共享/取消共享、删除项目、读取网络地图定义
- **管理用户**：列出用户、获取详细用户配置文件
- **管理组**：列出组、创建组、邀请用户
- **发布服务**：上传文件并发布为托管要素服务
- **运行地理处理**：执行同步和异步 GP 任务
- **Portal 管理**：系统信息、许可证管理、使用情况统计
- **批量操作**：批量删除、共享和更新多个项目
- **健康检查** 门户系统状态（需要管理员权限）
## 设计原则
- **无 `arcgis` Python 包依赖**：使用原始 REST API 调用通过 `requests` 实现最大兼容性（无需安装 `arcgis` 包）
- **适用于 Enterprise Portal 和 ArcGIS Online**：相同的工具，相同的 API
- **基于令牌的身份验证**：支持现有令牌、用户名/密码和 OAuth2 以实现完全灵活性
- **自动连接**：启动时读取 `.env` 文件，无需手动身份验证
- **2FA 友好**：适用于需要双因素身份验证的 Enterprise 门户（客户端凭证，无浏览器）
- **自签名证书友好**：处理具有自签名证书的 Enterprise 门户
## 安装
```bash
# 从源码
cd arcgis-portal-mcp
pip install -e .
# 或从 GitHub 安装
pip install git+https://github.com/Asem-D/arcgis-portal-mcp.git
```
**Windows 用户：** `pywin32` 作为特定于平台的依赖项自动安装。
## 配置
### `.env` 文件（推荐）
在项目根目录中创建 `.env` 文件，以便在启动时自动连接。提供了一个模板：
```bash
cp .env.example .env
# 编辑 .env 文件以包含您的门户凭证
```
```env
portal_url=https://gis.example.com/portal
# 选项 1：用户名/密码（大多数用户推荐）
username=您的门户用户名
password=您的门户密码
# 选项 2：OAuth2 应用凭证（应用级，权限有限）
# oauth_client_id=您的oauth应用客户端ID
# oauth_client_secret=您的oauth应用客户端密钥
```
服务器在启动时读取这些配置并自动连接。如果提供了 `username` + `password`，则使用 `generateToken`（用户级，完全权限）。否则，服务器会回退到 `client_credentials`（应用级，权限有限）。无需手动 `connect_portal` 调用。
> **注意：** `.env` 文件被 gitignore。切勿提交凭证。`.env.example` 可以安全提交。
### MCP 客户端配置
对于 MCP 客户端（Claude Desktop、Cursor 等），最简单的设置使用 `.env` 文件：
```json
{
"mcpServers": {
"arcgis-portal": {
"command": "python",
"args": ["-m", "arcgis_portal_mcp.server"],
"cwd": "/path/to/arcgis-portal-mcp"
}
}
}
```
服务器从工作目录中的 `.env` 文件自动连接。MCP 配置中不需要环境变量。
或者，通过 MCP 客户端环境变量传递凭证：
```json
{
"mcpServers": {
"arcgis-portal": {
"command": "python",
"args": ["-m", "arcgis_portal_mcp.server"],
"env": {
"portal_url": "https://gis.example.com/portal",
"username": "您的门户用户名",
"password": "您的门户密码"
}
}
}
}
```
### `connect_portal` 工具参数
`connect_portal` 工具接受以下 `auth_method` 值：
| 值 | 行为 |
|-------|----------|
| `auto` | 从 `.env` 读取（默认）- 尝试用户名/密码，然后是客户端凭证 |
| `username_password` | 门户用户名 + 密码 -> 生成令牌（用户级） |
| `token` | 使用明确的门户令牌 |
| `client_credentials` | 使用明确的客户端 ID/密钥 |
| `oauth2` | 基于浏览器的 OAuth2（阻塞 ~2 分钟） |
## 用法
### 连接和搜索
```
用户：搜索门户中的所有要素服务
代理：[调用 connect_portal，然后使用 item_type="要素服务" 调用 search_content]
```
### 查询图层
```
用户：显示 cadastral 图层的前 10 个地块
代理：[调用 list_layers 查找地块图层，然后使用 limit=10 调用 query_features]
```
### 审计用户
```
用户：我们门户中的管理员是谁？
代理：[调用 list_users，按角色过滤]
```
### 添加要素
```
用户：在基础设施图层中添加这 3 个建筑物
代理：[调用 add_features，包含要素服务 URL 和 JSON 要素]
```
### 共享网络地图
```
用户：与“规划团队”组和整个组织共享项目 abc123
代理：[调用 share_item，包含 org=true 和 groups=<planning-team-id>]
```
### 读取网络地图
```
用户：这个网络地图中有哪些底图和图层？
代理：[调用 get_item_data 读取网络地图 JSON，总结底图和操作图层]
```
### 发布 Shapefile
```
用户：将此 Shapefile 发布为托管要素服务
代理：[调用 upload_item 上传 .zip 文件，然后调用 publish_from_item 创建服务]
```
### 运行地理处理任务
```
用户：对地块图层运行缓冲区分析，距离为 100m
代理：[调用 execute_gp_task，包含 GP 服务 URL 和输入参数]
```
### 批量操作
```
用户：删除所有我的草稿项目
代理：[调用 search_content 查找项目，然后调用 batch_delete_items 删除它们]
```
### 门户管理
```
用户：我们还剩多少个许可证？
代理：[调用 list_licenses 显示许可证分配和使用情况]
```
## 可用工具
### 第一阶段：只读（v0.1）
| 工具 | 描述 |
|------|-------------|
| `connect_portal` | 与门户进行身份验证（自动、令牌、客户端凭证或 OAuth2） |
| `search_content` | 按关键词、类型和所有者搜索项目 |
| `get_item_details` | 获取特定项目的详细元数据 |
| `list_layers` | 列出要素/地图服务中的图层 |
| `query_features` | 查询要素并使用筛选器和分页 |
| `list_users` | 列出门户用户及其角色和状态 |
| `list_groups` | 列出门户组及其访问级别 |
| `portal_health` | 检查门户健康状况和系统状态 |
| `server_status` | 检查 MCP 服务器连接状态 |
### 第二阶段：要素 CRUD、用户/组和内容管理（v0.2）
| 工具 | 描述 |
|------|-------------|
| `add_features` | 向托管要素图层添加新要素 |
| `update_features` | 更新现有要素（按 OBJECTID） |
| `delete_features` | 按 OBJECTID 或 WHERE 子句删除要素 |
| `get_user_details` | 获取详细用户配置文件（角色、特权、存储、最后登录） |
| `create_group` | 创建具有访问控制的新组 |
| `invite_to_group` | 邀请用户加入具有角色分配的组 |
| `update_item` | 更新项目属性（标题、描述、标签、访问权限） |
| `delete_item` | 从门户删除项目 |
| `share_item` | 与所有人、组织或特定组共享/取消共享项目 |
| `get_item_data` | 读取项目数据（网络地图 JSON、应用配置、要素集合） |
### 第三阶段：发布、地理处理、管理和管理（v1.0）
| 工具 | 描述 |
|------|-------------|
| `upload_item` | 将本地文件（CSV、Shapefile 等）上传到门户内容 |
| `publish_from_item` | 将上传的项目发布为托管要素服务 |
| `create_service` | 创建具有架构的空托管要素服务 |
| `execute_gp_task` | 运行同步地理处理任务 |
| `submit_gp_job` | 提交异步 GP 作业并获取作业 ID 进行轮询 |
| `get_gp_job_status` | 检查正在运行的异步地理处理作业的状态 |
| `portal_system_info` | 获取门户版本、平台和系统信息（管理员） |
| `list_licenses` | 获取许可证信息和分配（管理员） |
| `portal_usage` | 获取门户使用情况统计：用户、API 调用、存储（管理员） |
| `batch_delete_items` | 一次性删除多个项目 |
| `batch_share_items` | 与相同受众共享/取消共享多个项目 |
| `batch_update_items` | 一次更新多个项目的属性 |
## 身份验证方法
| 方法 | 优点 | 缺点 |
|--------|------|------|
| **自动** （默认） | 零配置，启动时读取 `.env` | 仅限应用级（无用户身份） |
| **令牌** | 快速，无依赖 | 令牌过期，必须单独获取 |
| **客户端凭证** | 无需浏览器，自动刷新 | 仅限应用级（无用户身份） |
| **OAuth2** | 完全用户权限，14 天令牌 | 打开浏览器，阻塞约 2 分钟 |
**适用于具有 2FA 的企业门户的推荐：** 使用 `auto`（`.env` 包含 `client_credentials`）。令牌身份验证将不起作用，因为 2FA 阻止令牌生成。`client_credentials` 流使用应用级 OAuth2，无需浏览器，无需 2FA，无需用户交互。
**适用于 ArcGIS Online 或无 2FA 的门户：** 令牌身份验证是 MCP 最快的身份验证方式。使用 OAuth2 一次获取长期令牌，然后在 MCP 会话中使用该令牌。
## 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest
# 运行 linting
ruff check arcgis_portal_mcp/
```
## 许可证
MIT。参见 [LICENSE](LICENSE)。
## 作者
Asem Daaboul ([asem.daaboul@gmail.com](mailto:asem.daaboul@gmail.com))
