umbrella MCP

思科伞式MCP服务器

特性

• 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凭据

1. 登录到 思科伞形仪表板
2. 引导到 管理员→ API密钥 （在左侧边栏的“管理”部分下）
3. 点击 创建 生成新的API密钥对
4. 给密钥一个描述性名称（例如。， MCP-Server-Key)
5. 在...之下 关键范围，选择所需的范围：

- 报告 --DNS活动、主要威胁、主要目的地、摘要所需 - 部署 --漫游计算机、隧道组、站点需要 - 政策 --目标列表、专用资源、访问策略需要 - 调查 --域/IP/URL威胁查找所需 - 管理员 --VPN连接、警报、集成所需

1. 复制 客户端ID 和 客户端密钥 （秘密只显示一次！）
2. 注意你的 组织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 取决于端点类型：

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 头球

要设置多租户访问：

1. 登录您的Umbrella仪表板 母公司/管理组织
2. 在那里创建一个带有所需作用域的API键
3. 查找每个子组织的组织ID：

- 首选 管理员→ 账户 在Umbrella仪表板中 - 或者检查URL——它通常包含组织ID（例如。， https://dashboard.umbrella.com/o/1234567/)

1. 集 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/远程访问

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

活动和报告

网络隧道

部署

通用工具（7）

API节和终结点计数

配置参考

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

用法示例

查询被阻止的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"

缓存

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

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

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

错误处理

故障排除

“必须设置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许可证

资源

• Cisco Secure Access API文档
• 伞式API参考
• 模型上下文协议规范
• FastMCP框架