umbrella MCP

MCP安全风控

提供方 demon0110

安全风控 stdio · 本地进程 API Key 社区 / 第三方 Claude DesktopClaude
查看接入方式

一个基于FastMCP构建的生产级MCP服务器,提供对87+ Cisco Umbrella API端点的全面访问,适用于AI助手直接与Umbrella安全平台交互的场景。

一句话选型结论

按资料字段整理

umbrella MCP 属于安全风控类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Claude Desktop、Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类安全风控 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 22 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

安全风控
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量22暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

安全APIPython本地部署网络管理AI集成OAuth2认证多租户支持

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
python3 -m venv .venv

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 22 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
资产与漏洞排查

盘点资产、扫漏洞、看暴露面。

日志与审计

汇总日志、查异常行为。

合规检查

按规则检查配置与权限是否合规。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 22 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在安全风控场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
umbrella MCP当前 22 stdio · 本地进程 本地部署 有 2026-05-17
Cyber Strike AI 75 未标注 未标注 无 2026-05-17
mcp-for-beginners 未标注 stdio · 本地进程 本地部署 有 2026-04-13
casdoor 未标注 stdio · 本地进程 本地部署 有 2026-04-12
kubeshark 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Modelcontextprotocol C22988b0 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

安全风控
字段来自项目仓库与公开索引,中文说明由本站标注
提供方demon0110上游标注的维护方 demon0110
分类安全风控本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

14.8 KB
来自项目仓库与上游目录的原文,未做删改

思科伞式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.克隆存储库```bash
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连接、警报、集成所需
  6. 复制 客户端ID 和 客户端密钥 (秘密只显示一次!)
  7. 注意你的 组织ID (在Umbrella仪表板URL或“管理”下可见→ 账户)

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

3.配置环境```bash

cp .env-example .env


#### 单一组织(最常见)

如果您只管理一个Umbrella组织 `.env` 很简单:```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:```env
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仪表板 **母公司/管理组织**
1. 在那里创建一个带有所需作用域的API键
1. 查找每个子组织的组织ID:
- 首选 **管理员→ 账户** 在Umbrella仪表板中
- 或者检查URL——它通常包含组织ID(例如。, `https://dashboard.umbrella.com/o/1234567/`)
1. 集 `CISCO_ORG_ID` 在你的 `.env` 到您要查询的组织```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 文件夹:```bash

.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`:```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:使用安装脚本(推荐)```bash
chmod +x setup.sh
./setup.sh


**选项B:手动安装**```bash
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````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"


## 缓存

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

1. **内存缓存** --基于字典的快速查找最近访问的GET端点。通过方法+路径+参数的SHA-256哈希值设置密钥。
1. **文件缓存** --持久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许可证

资源

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

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
umbrella MCP 怎么安装?

在客户端按下面的安装命令接入:python3 -m venv .venv。装完在客户端配置里引用同一个包或端点。

umbrella MCP 怎么在 Claude Desktop、Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

umbrella MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

umbrella MCP 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

umbrella MCP 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

umbrella MCP 能提供哪些能力?

资料显示约 22 个工具;能力标签包括 Python、Claude、网络管理。具体工具清单以官方文档为准。

umbrella MCP 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

umbrella MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。