cisco-umbrella-mcp

Cisco Umbrella MCP 服务 —— 一个无状态的 HTTP MCP 服务器，封装了 Cisco Umbrella REST API v2（经典 Umbrella，而非较新的 Secure Access/SASE 产品），范围限定为 MSPbots 当前使用的 10 个端点：DNS/代理/防火墙/AMP 追溯活动报告、漫游计算机、应用发现（应用程序/协议/应用类别）、托管提供商客户列表以及提供商控制台摘要。

技术栈： Python 3.12 + uv + FastMCP（Starlette/Uvicorn）

代理何时会使用此服务

Cisco Umbrella 在 DNS/Web 层保护客户网络——它阻止恶意域名、按类别过滤 Web 内容并记录网络活动。代理应针对以下请求使用此 MCP：

• “该域名最近是否在此客户网络上被查询或阻止？” → cisco_umbrella_get_activity_dns

• “此客户正在过滤或代理哪些 Web 类别/URL？” → cisco_umbrella_get_activity_proxy

• “过去一天内此客户网络是否有防火墙允许/阻止记录？” → cisco_umbrella_get_activity_firewall

• “看起来干净的文件后来是否被标记为恶意软件？” → cisco_umbrella_get_activity_amp_retrospective

• “列出此客户的漫游笔记本电脑及其上次同步/状态” → cisco_umbrella_list_roaming_computers

• “列出我们在 Cisco Umbrella 下管理的客户组织” / “我们跨客户的 Umbrella 套餐使用情况如何？” → cisco_umbrella_list_customers, cisco_umbrella_get_providers_console

注意事项： 此凭据集是托管提供商（MSSP）根组织密钥，而非按客户凭据，因此上述按客户的活动/设备工具在实践中可能返回空结果——请参阅下面的 已知差距 了解已验证的详细信息。

Related MCP server: cisco-secure-access-mcp

身份验证方法说明

Cisco Umbrella 的经典 REST API 支持 OAuth2 client_credentials 授权——纯服务器到服务器交换，无需用户浏览器重定向。管理员在 Umbrella 仪表板（Admin > API Keys）中创建 API Key + Key Secret 对，此服务在每次调用时将该对交换为短期（1 小时）的 bearer token（无刷新令牌，因此无跨请求缓存——与 covedataprotection-mcp/webroot-mcp/logmein-mcp 相同的“每次调用重新登录”模式）。

POST https://api.umbrella.com/auth/v2/token
Authorization: Basic base64(apiKey:keySecret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

区域说明： MSPbots 自己的 Cisco Umbrella 集成配置有一个 dataCenter 字段（us/eu）。直接对照 Cisco 官方开发者文档中嵌入的原始 OpenAPI 规范验证了全部 10 个端点以及认证/token 端点：每个端点都只列出一个主机，https://api.umbrella.com——经典 Umbrella 没有单独的 EU 主机。（Cisco 较新的“Secure Access”产品确实有自己的区域概念，但那是与本服务目标不同的产品。）因此，此服务完全忽略 dataCenter 值；这 10 个端点都不需要它。

快速开始

# Install dependencies
cd D:\claude\project\cisco-umbrella-mcp
uv sync

# Run in stdio mode (for Claude Desktop)
$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

配置

将 .env.example 复制为 .env 并填写你的值：

HEADER 授权参数说明

网关模式下，每个请求必须携带以下两个 HTTP Header：

Claude Desktop 设置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "cisco-umbrella": {
      "command": "uv",
      "args": ["run", "--directory", "D:/claude/project/cisco-umbrella-mcp", "cisco-umbrella-mcp"],
      "env": {
        "UMBRELLA_API_KEY": "your_api_key",
        "UMBRELLA_KEY_SECRET": "your_key_secret"
      }
    }
  }
}

传输模式

stdio（Claude Desktop / CLI）

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
uv run cisco-umbrella-mcp

HTTP — 单租户

$env:UMBRELLA_API_KEY="your_api_key"
$env:UMBRELLA_KEY_SECRET="your_key_secret"
$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="env"
uv run cisco-umbrella-mcp

HTTP — 网关 / 多租户

$env:MCP_TRANSPORT="http"
$env:AUTH_MODE="gateway"
uv run cisco-umbrella-mcp
# Each request must include: X-Umbrella-Api-Key and X-Umbrella-Key-Secret headers

可用工具（10 个）

from_/to 接受纪元毫秒、ISO-8601 或相对偏移量（例如 "-1days"、"-7days"、"now"），遵循 Umbrella 报告 API 约定。（from_ 有尾随下划线，因为 from 是 Python 保留字——它在内部映射为字面量 from 查询参数。）

已知差距

已针对两个真实的托管提供商（MSSP）账户进行测试。在 10 个工具中，只有 2 个确认可用且具有已验证的真实数据；其他 8 个要么被阻止，要么未验证（空结果不能证明正确性——仅表示未引发错误）。

✅ 确认可用（真实、非空、交叉验证的数据）：

• cisco_umbrella_get_providers_console — 两个测试账户均返回真实订阅摘要（分别为 customerCount: 77 和 customerCount: 47）。

• cisco_umbrella_list_customers — 账户 1 返回 77 个真实客户组织（真实公司名称）。账户 2 上失败，返回 403 Access Forbidden——通过解码该账户的 token 确认其确实缺少 admin.customers:read 范围（总共 20 个范围，而账户 1 有 76 个）。这不是代码错误，而是真实的按密钥权限差异。

⚠️ 未验证——在两个账户上均返回格式正确但为空的结果，未证明正确： cisco_umbrella_get_activity_dns、_proxy、_firewall、_amp_retrospective、cisco_umbrella_list_roaming_computers。已直接对照 Cisco 官方文档交叉检查 Activity DNS 的实时 OpenAPI 参数定义（拉取了原始规范，而非摘要）——from/to/limit 与实现完全一致，没有缺失或命名错误的参数。可能的解释是，两个测试账户都是 托管提供商根组织，它们本身没有直接的 DNS/代理/防火墙/AMP 流量或漫游计算机——这些数据位于每个 托管客户 组织下。搜索了 Cisco 文档，寻找经典 Umbrella 的“以该客户组织身份查询”的范围参数/请求头——未找到（存在“Multi-Org” token 范围概念，但仅适用于单独的 Secure Access/SASE 产品，而非经典 Umbrella）。有一个独立的“Providers” API 系列（/providers/customers/{customerId}/...），看起来可能是获取按客户数据的预期路径，但超出了本次构建确认的 10 端点范围。需要真实的单客户组织凭据（而非提供商级别）才能实际确认这 5 个工具。

• cisco_umbrella_list_applications、_protocols、_application_categories（App Discovery）——已确认被阻止，并非代码缺陷。 在两个测试账户上以及通过直接 curl 使用相同令牌均复现了相同结果（排除了请求构造问题）：账户 1 返回 403 Access Forbidden，账户 2 返回 500/403。两个令牌的 scope 列表均包含 reports.appdiscovery:read，因此这很可能是套餐/授权限制（App Discovery 作为付费附加功能，未包含在两个账户的"Umbrella for MSSPs"层级中），而非权限或参数问题。

• cisco_umbrella_get_providers_console 返回的是单个订阅摘要对象，而非列表——已通过两次实时测试确认。尽管 MSPbots 自身配置的 API 列表中使用了复数名称（"Providers Consoles"），请与 MSPbots 现有采集器所期望的格式（数组 vs 单个对象）进行核对。

• Applications 应用发现端点的可选参数列表可能并非完全详尽（研究期间该端点 schema 末尾的几个参数未被完整捕获）——此处记录的参数（sources、identity、labels、controllable、categories、subcategory、limit、offset）已确认为真实存在；可能还有一两个尚未添加。

• 范围仅限于 MSPbots 当前使用的 10 个操作（经用户确认），而非 Umbrella 的完整 API 面（后者还包括 Networks、Internal Domains、Sites、Network Tunnels、Policies、Tagging、用于按客户操作的独立"Providers"API，以及用于管理 API 密钥本身的 Key Admin API）。

API 参考

• Cisco Umbrella API 身份验证

• Cisco Cloud Security API 文档（DevNet）