使用说明

思科伞式MCP服务器

生产准备就绪模型上下文协议（MCP）用于查询和管理思科安全访问（Umbrella）基础设施的服务器。建于 FastMCP，此服务器提供对以下内容的全面访问 87+伞状API终点 跨越5个API部分-使Claude等人工智能助手能够直接与Umbrella安全平台交互。

特性

OAuth2身份验证 --通过具有60秒刷新缓冲区的客户端凭据流进行自动令牌管理
87+API终点 --涵盖管理、部署、报告、调查和策略部分
16个预先注册的工具 --针对最常见操作（VPN、DNS、威胁、隧道等）的优化工具
通用API网关 — call_umbrella_api 该工具提供对所有87个以上注册端点的访问
两层缓存 --内存+基于文件的缓存，具有可配置的TTL（默认5分钟）
多租户支持 --可选 X-Umbrella-OrgId 多组织环境的标题
只读模式 --通过阻止写入操作来强制执行安全的审计/报告工作流程
自动401重试 --令牌刷新和身份验证失败时请求重试
方法发现 -搜索并列出运行时可用的API方法

建筑

┌──────────────────────┐     ┌──────────────────────┐     ┌──────────────────────┐
│   Claude Desktop /   │     │   Umbrella MCP       │     │   Cisco Umbrella     │
│   AI Assistant       │────▶│   Server (FastMCP)   │────▶│   API                │
│                      │ MCP │                      │HTTP │                      │
│   - 16 direct tools  │◀────│   - OAuth2 tokens    │◀────│   - Reports v2       │
│   - Generic API call │     │   - Request caching  │     │   - Deployments v2   │
│   - Method discovery │     │   - File caching     │     │   - Policies v2      │
└──────────────────────┘     └──────────────────────┘     │   - Admin v2         │
                                                          │   - Investigate v2   │
                                                          └──────────────────────┘

快速开始

1.克隆存储库

git clone https://github.com/demon0110/umbrella_mcp.git
cd umbrella_mcp

2.获取API凭据

登录到思科伞形仪表板
引导到 管理员→ API密钥 （在左侧边栏的“管理”部分下）
点击创建生成新的API密钥对
给密钥一个描述性名称（例如。， MCP-Server-Key)
在...之下 关键范围，选择所需的范围：
- 报告 --DNS活动、主要威胁、主要目的地、摘要所需
- 部署 --漫游计算机、隧道组、站点需要
- 政策 --目标列表、专用资源、访问策略需要
- 调查 --域/IP/URL威胁查找所需
- 管理员 --VPN连接、警报、集成所需
复制 客户端ID 和 客户端密钥 （秘密只显示一次！）
注意你的 组织ID （在Umbrella仪表板URL或“管理”下可见→ 账户）

重要提示： 每个API键的作用域为组织创建时您已登录。如果您管理多个Umbrella组织，请参阅多租户设置在......下面

3.配置环境

cp .env-example .env

单一组织（最常见）

如果您只管理一个Umbrella组织 .env 很简单：

# Required — from Umbrella Admin → API Keys
CISCO_CLIENT_ID="your-client-id-here"
CISCO_CLIENT_SECRET="your-client-secret-here"

# Optional — set this if API calls return data for the wrong org,
# or if your account has access to multiple orgs
CISCO_ORG_ID=""

双基URL（保护伞+安全访问）

Cisco的API平台使用 两个不同的基本URL 取决于端点类型：

基本URL	用于	端点
`https://api.umbrella.com`	报告、调查、策略	DNS活动、代理日志、威胁、摘要
`https://api.sse.cisco.com`	部署、管理	隧道组、漫游计算机、VPN连接

MCP服务器自动处理此问题-报告将转到Umbrella，而部署/管理调用将路由到安全访问（SSE）API。两者都使用相同的OAuth2令牌。

如果需要，您可以通过环境变量覆盖任一基本URL：

CISCO_BASE_URL="https://api.umbrella.com"        # Default for reports
CISCO_SSE_BASE_URL="https://api.sse.cisco.com"    # Default for deployments/admin

多租户设置

如果您管理多个Umbrella组织（例如，作为MSP或与父/子组织一起管理），您需要了解API密钥和组织ID是如何协同工作的：

它是如何工作的： 在Umbrella中创建API密钥时，将生成该密钥 在您当前登录的组织的上下文中。密钥的凭据（客户端ID+密钥）对您进行身份验证 CISCO_ORG_ID 告诉API通过 X-Umbrella-OrgId 头球

要设置多租户访问：

登录您的Umbrella仪表板 母公司/管理组织
在那里创建一个带有所需作用域的API键
查找每个子组织的组织ID：
- 首选 管理员→ 账户 在Umbrella仪表板中
- 或者检查URL——它通常包含组织ID（例如。， https://dashboard.umbrella.com/o/1234567/)
集 CISCO_ORG_ID 在你的 .env 到您要查询的组织

# Required — API key created in the PARENT/management organization
CISCO_CLIENT_ID="your-parent-org-client-id"
CISCO_CLIENT_SECRET="your-parent-org-client-secret"

# Required for multi-tenant — specify which child org to query
# This sends the X-Umbrella-OrgId header with every API request
CISCO_ORG_ID="1234567"

注：如果你需要同时查询多个组织，你可以运行 单独实例 MCP服务器，每个都有自己的 .env 指向不同的 CISCO_ORG_ID.在你的 claude_desktop_config.json为每个实例赋予一个唯一的名称（例如。， Umbrella_OrgA, Umbrella_OrgB).

示例——并行运行两个组织：

创建单独 .env 文件夹：

# .env.org-a
CISCO_CLIENT_ID="parent-key-client-id"
CISCO_CLIENT_SECRET="parent-key-client-secret"
CISCO_ORG_ID="1111111"

# .env.org-b
CISCO_CLIENT_ID="parent-key-client-id"
CISCO_CLIENT_SECRET="parent-key-client-secret"
CISCO_ORG_ID="2222222"

然后在 claude_desktop_config.json:

{
  "mcpServers": {
    "Umbrella_OrgA": {
      "command": "/path/to/umbrella_mcp/.venv/bin/python",
      "args": ["/path/to/umbrella_mcp/umbrella-mcp.py"],
      "env": {
        "CISCO_CLIENT_ID": "parent-key-client-id",
        "CISCO_CLIENT_SECRET": "parent-key-client-secret",
        "CISCO_ORG_ID": "1111111"
      }
    },
    "Umbrella_OrgB": {
      "command": "/path/to/umbrella_mcp/.venv/bin/python",
      "args": ["/path/to/umbrella_mcp/umbrella-mcp.py"],
      "env": {
        "CISCO_CLIENT_ID": "parent-key-client-id",
        "CISCO_CLIENT_SECRET": "parent-key-client-secret",
        "CISCO_ORG_ID": "2222222"
      }
    }
  }
}

提示： 使用时 env 挡住 claude_desktop_config.json，这些值覆盖了 .env 文件。这是多组织设置中最干净的方法，因为您可以重用相同的代码库。

4.安装依赖项

选项A：使用安装脚本（推荐）

chmod +x setup.sh
./setup.sh

选项B：手动安装

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

5.配置克劳德桌面

将以下内容添加到您的 claude_desktop_config.json:

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "Umbrella_MCP": {
      "command": "/path/to/umbrella_mcp/.venv/bin/python",
      "args": ["/path/to/umbrella_mcp/umbrella-mcp.py"]
    }
  }
}

注：服务器从读取凭据 .env 项目目录中的文件。或者，您可以通过 env 块在上面的配置中。

6.重新启动克劳德桌面

保存配置后，完全重新启动Claude Desktop。Umbrella MCP工具应出现在工具列表中。

可用工具

预注册工具（16）

这些是针对最常见工作流程优化的一流MCP工具：

VPN/远程访问

工具	说明	关键参数
`getVpnOverview`	实时连接+历史VPN事件组合	`time_from`, `time_to`, `limit`
`getRemoteAccessEvents`	历史VPN连接/断开连接日志	`time_from`, `time_to`, `limit`, `offset`

注：实时VPN连接端点(/admin/v2/vpn/userConnections)当没有用户处于活动连接状态时，返回404。这是Umbrella API的正常行为。这 getVpnOverview 工具通过返回一个 no_active_connections 状态而不是错误。

活动和报告

工具	说明	关键参数
`getActivityDns`	查询DNS活动记录	`time_from`, `time_to`, `verdict`, `domains`
`getActivityProxy`	查询代理/网络活动记录	`time_from`, `time_to`, `verdict`
`getActivityFirewall`	查询防火墙活动记录	`time_from`, `time_to`
`getActivityZtna`	查询ZTNA活动记录	`time_from`, `time_to`
`getSummary`	获取汇总统计信息	`time_from`, `time_to`
`getTopThreats`	按计数获取最大威胁	`time_from`, `time_to`, `limit`
`getTopIdentities`	获取顶级用户/身份	`time_from`, `time_to`, `limit`

网络隧道

工具	说明	关键参数
`getNetworkTunnelGroups`	列出所有隧道组（安全连接/IPsec）	--
`getNetworkTunnelGroupStates`	获取隧道活动/非活动/未建立状态	--
`getNetworkTunnelGroupById`	获取特定隧道组的详细配置	`tunnel_group_id`
`getNetworkTunnelGroupPeers`	获取隧道组的IPsec对等体	`tunnel_group_id`
`getNetworkTunnelLogs`	隧道上行/下行事件和流量日志	`time_from`, `time_to`, `limit`

部署

工具	说明	关键参数
`getRoamingComputers`	获取端点清单	`limit`, `offset`

通用工具（7）

工具	说明
`call_umbrella_api`	呼叫任何按节和方法名称注册端点
`list_all_methods`	发现可用的API方法（可选择按部分筛选）
`search_methods`	按关键字搜索方法
`get_cached_response`	从磁盘检索分页缓存的响应
`cache_stats`	查看缓存统计信息和配置
`cache_clear`	清空所有内存和基于文件的缓存
`get_mcp_config`	查看当前服务器配置

API节和终结点计数

第节	端点	描述
管理员	12	VPN用户、API密钥、ZTNA、集成、警报、租户
部署	20	隧道组、连接器、漫游计算机、站点、内部域
报告	41	活动日志、顶级列表、摘要、带宽、部署状态
调查	3	域名、IP和URL威胁调查
政策	11	目的地列表、专用资源、访问策略、网络/服务对象

配置参考

所有配置都是通过中的环境变量完成的 .env:

变量	必填	默认	描述
`CISCO_CLIENT_ID`	是	--	Umbrella仪表板上的OAuth2客户端ID
`CISCO_CLIENT_SECRET`	是	--	OAuth2客户端密码
`CISCO_ORG_ID`	无	--	多租户模式的组织ID
`CISCO_BASE_URL`	没有	`https://api.umbrella.com`	API基本URL
`CISCO_AUTH_URL`	没有	`{base_url}/auth/v2/token`	OAuth2令牌终结点
`ENABLE_CACHING`	没有	`true`	启用/禁用响应缓存
`CACHE_TTL_SECONDS`	没有	`300`	缓存生存时间（秒）
`READ_ONLY_MODE`	没有	`false`	阻止所有写入（PUT/POST/DELETE）操作
`ENABLE_FILE_CACHING`	没有	`true`	为大型响应启用基于磁盘的缓存
`MAX_RESPONSE_TOKENS`	没有	`5000`	最大响应令牌大小
`MAX_PER_PAGE`	没有	`100`	每个分页请求的最大项目数
`RESPONSE_CACHE_DIR`	没有	`~/.umbrella_cache`	自定义缓存目录路径

用法示例

查询被阻止的DNS活动

Tool: getActivityDns
  time_from: "2026-03-01T00:00:00Z"
  time_to: "2026-03-11T23:59:59Z"
  verdict: "blocked"
  limit: 50

获取最大威胁

Tool: getTopThreats
  time_from: "2026-03-01T00:00:00Z"
  time_to: "2026-03-11T23:59:59Z"
  limit: 10

列出活动VPN连接

Tool: getVpnUserConnections
  limit: 50

通过通用工具调用任意端点

Tool: call_umbrella_api
  section: "policies"
  method_name: "getDestinationLists"
  parameters: {}

调查可疑域名

Tool: call_umbrella_api
  section: "investigate"
  method_name: "investigateDomain"
  parameters: {"domain": "suspicious-site.com"}

发现可用方法

Tool: search_methods
  keyword: "tunnel"

缓存

服务器实现了两层缓存策略：

内存缓存 --基于字典的快速查找最近访问的GET端点。通过方法+路径+参数的SHA-256哈希值设置密钥。
文件缓存 --持久JSON文件存储在 ~/.umbrella_cache/ （可配置）。适用于超出上下文窗口限制的大型响应。

缓存条目在配置的TTL（默认值：300秒）后自动失效。使用 cache_clear 手动刷新所有缓存的工具，或 cache_stats 以检查当前缓存状态。

错误处理

场景	行为
401未经授权	自动清除令牌、刷新并重试请求一次
无效凭证	加薪 `ValueError` 启动时提供获取凭据的说明
只读违规	在只读模式下尝试写入操作时返回错误消息
网络错误	传播为 `httpx` 描述性消息的例外情况

故障排除

“必须设置CISCO_CLIENT_ID和CISCO_CLEENT_SECRET”

确保您的 .env 文件存在于项目根目录中，并包含有效凭据
验证 .env 正在加载文件（检查工作目录）

报告端点上的400个错误请求

验证您的API密钥是否具有报告 Umbrella仪表板中启用了作用域
新的API密钥可能需要15-30分钟才能传播
某些报告端点需要特定的Umbrella许可证级别（Advantage/SIG）

401重试后仍存在错误

在Umbrella仪表板中重新生成API键
确认 CISCO_BASE_URL 匹配您的部署（umbrella.com vs sse.cisco.com）

慢查询

使用 time_from 和 time_to 缩小时间范围
检查 cache_stats 验证缓存是否正常工作
减少 limit 对于大型结果集

项目结构

umbrella_mcp/
├── umbrella-mcp.py      # Main MCP server (all-in-one)
├── .env-example          # Template for environment variables
├── .env                  # Your actual credentials (git-ignored)
├── .gitignore            # Git ignore rules
├── requirements.txt      # Python dependencies
├── pyproject.toml        # Project metadata
├── setup.sh              # Automated setup script
└── README.md             # This file

需求

Python 3.10+
mcp[cli]>=1.0.0 --模型上下文协议SDK
httpx>=0.27.0 --异步HTTP客户端
pydantic>=2.0.0 --数据验证
python-dotenv>=1.0.0 --环境变量管理

许可证

MIT许可证