SOAR MCP Server

基于 OctoMation SOAR 平台 的 Model Context Protocol (MCP) 服务器，为 Claude Desktop、Cherry Studio、Cursor、Trae 等 AI 客户端提供安全编排、自动化和响应能力。

功能特性 • 快速开始 • 从旧版本升级 • 管理工具 • 配置说明 • 安全特性 • 故障排除

概述

SOAR MCP Server 是一个创新的安全编排平台集成解决方案，专为 。通过 Model Context Protocol 将 SOAR (Security Orchestration, Automation and Response) 能力直接集成到各种 AI 客户端中，包括 Claude Desktop、Cherry Studio、Cursor、Trae 等。它提供了完整的安全事件管理、剧本执行、威胁情报查询等功能，让 AI 助手具备专业的网络安全响应能力。

🏗️ 系统架构

SOAR MCP Server 采用双服务器架构设计，包含 MCP 服务器、Web 管理服务器、业务逻辑层、数据存储层和外部系统集成层，提供完整的安全编排自动化解决方案。

技术架构要点

🎯 OctoMation SOAR 平台

本项目专为 OctoMation SOAR 平台 设计，OctoMation 是一个功能强大的安全编排、自动化和响应平台，提供：

• 🛡️ 完整的安全工具链：支持主流安全产品和平台

• 📚 丰富的安全剧本：预置大量实用的安全响应剧本

• 🔄 灵活的工作流：可视化剧本编排和自动化执行

• 🌐 开放架构：支持自定义集成和扩展

核心优势

• 🔒 安全编排：无缝对接 OctoMation SOAR 平台

• 🤖 AI 驱动：通过多种 AI 客户端实现智能安全响应

• ⚡ 异步架构：MCP 工具函数全异步，httpx 连接池复用

• 🌐 Web 管理：直观的可视化管理界面

• 🔧 灵活配置：支持多种部署和配置方式

• 🛡️ 安全加固：bcrypt 密码哈希、JWT 密钥持久化、日志脱敏

功能特性

🛠️ MCP 工具集

SOAR MCP 服务器提供的完整工具集

剧本查询与执行

• list_playbooks_quick - 获取简洁的剧本列表（ID、name、displayName），适用于 AI 快速理解剧本选项

• query_playbook_execution_params - 根据剧本ID查询执行所需的参数定义

• execute_playbook - 执行指定的 SOAR 剧本，支持参数传递（异步）

• query_playbook_execution_status_by_activity_id - 根据活动ID查询剧本执行状态（异步）

• query_playbook_execution_result_by_activity_id - 根据活动ID查询剧本执行的详细结果（异步）

重要说明

• 剧本ID格式：支持 LONG 类型（64位整数），可以使用整数或字符串格式

• 执行流程：查询参数 → 执行剧本 → 检查状态 → 获取结果

• 兼容性：剧本ID 可能超出 JavaScript 安全整数范围，建议使用字符串格式

📊 MCP 资源

• soar://playbooks - SOAR 剧本列表

• soar://applications - SOAR 应用列表

• soar://executions - 执行活动记录

🌐 Web 管理界面

SOAR MCP 服务器 Web 管理界面 - 剧本管理页面

• 剧本管理：可视化剧本列表、状态管理、执行监控

• Token 管理：API 访问凭证的创建、管理和监控

• 系统配置：SOAR 连接设置、同步配置、SSL 验证开关

• 统计信息：系统状态、执行统计、同步时间

🚀 快速开始

本指南将带你从零开始部署和配置 SOAR MCP Server。

📋 环境要求

系统要求：

• Python 3.9+

• 4GB+ 内存

• 网络连接（用于 SOAR API 访问）

支持平台：

• Linux (Ubuntu 18.04+, CentOS 7+)

• macOS (10.14+)

• Windows 10/11

🛠️ 第一步：项目部署

1. 获取项目代码

2. 环境配置

3. 首次启动

🎉 恭喜！服务器已启动

首次运行时，系统会自动：

• ✅ 创建数据库和初始配置

• ✅ 生成管理员密码（仅在控制台显示一次，不写入日志文件）

• ✅ 生成并持久化 JWT 签名密钥

• ✅ 启动 MCP 服务器和 Web 管理界面

• ⚠️ 跳过 SOAR 剧本同步（需要后续配置）

重要输出信息：

⚠️ 安全提示：管理员密码仅在首次启动时通过控制台显示，不会记录到日志文件。请务必立即保存。如果遗失，可使用 ./reset_admin_password.sh 重置。

SOAR MCP 服务器启动后的控制台输出界面

⚙️ 第二步：SOAR 平台配置

1. 访问管理后台

1. 打开浏览器，访问 http://127.0.0.1:12346/admin

2. 使用控制台显示的管理员密码登录

3. 点击导航栏的「系统配置」

2. 配置 SOAR 连接

在系统配置页面填入以下信息：

3. 测试和保存

1. 点击「测试连接」按钮验证配置

2. 看到 ✅ "API连接测试成功！" 后，点击「保存配置」

3. 系统将自动开始同步 SOAR 剧本数据

🤖 第三步：MCP 客户端配置

支持多种基于大模型的 MCP 客户端，包括但不限于：Cherry Studio、Claude Desktop、Cursor、Trae 等。

Cherry Studio（推荐）

在 Cherry Studio 中配置 SOAR MCP 服务器

1. 打开 Cherry Studio

2. 进入设置 → MCP 服务器

3. 编辑配置文件，添加以下内容：

   方式一：URL 参数（兼容性好）

   { "mcpServers": { "soar-mcp": { "type": "http", "name": "soar-mcp", "description": "SOAR 安全编排平台集成", "url": "http://127.0.0.1:12345/mcp?token=xxxx" } } }

   方式二：Bearer Token（推荐，更安全）

   { "mcpServers": { "soar-mcp": { "type": "http", "name": "soar-mcp", "description": "SOAR 安全编排平台集成", "url": "http://127.0.0.1:12345/mcp", "headers": { "Authorization": "Bearer xxxx" } } } }

4. 保存并重启 Cherry Studio

在 Cherry Studio 中成功使用 SOAR MCP 服务器功能

⚠️ 重要：将 xxxx 替换为从管理后台获取的实际API Token。Bearer Token 方式更安全，Token 不会暴露在 URL 和日志中。

Claude Desktop

编辑 Claude Desktop 的 MCP 配置文件：

位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

配置内容（URL 参数方式）：

配置内容（Bearer Token 方式，推荐）：

⚠️ 重要：

• 将 xxxx 替换为从管理后台获取的实际API Token

• Bearer Token 方式更安全，推荐优先使用

• Claude Desktop 需要重启才能加载新配置

其他 MCP 客户端

通用配置参数：

• 协议: HTTP (Streamable-HTTP)

• 服务器 URL: http://127.0.0.1:12345/mcp

• 认证方式（二选一）:

  • 推荐: HTTP Header Authorization: Bearer <token>

  • 兼容: URL 参数 http://127.0.0.1:12345/mcp?token=xxxx

🧪 第四步：功能验证

验证 MCP 连接

在 MCP 客户端中输入：

正常情况下会返回：

完整执行流程示例

1. 查询剧本参数：

2. 执行剧本：

3. 查看执行状态：

4. 获取执行结果：

📦 从旧版本升级

如果你正在从 v1.0.x 升级到 v1.1.0+，请注意以下重要变更。

数据库兼容性

好消息：数据库结构基本兼容，旧版数据库可以直接复用。

唯一的破坏性变更：管理员密码哈希算法从 SHA-256 升级为 bcrypt。旧密码无法在新版本中验证，升级后必须重置。

升级步骤

提示：升级后所有 SOAR 配置、剧本数据、Token 等均自动保留，仅需重置管理员密码即可正常使用。

🔧 管理工具

管理员密码重置

如果忘记了管理员密码，可以使用密码管理脚本：

脚本特性：

• 🔒 使用 bcrypt 安全哈希（与服务器一致）

• 🎨 交互式彩色界面，支持密码确认

• ⚡ 密码立即生效，无需重启服务

• ✅ 自动检测虚拟环境和依赖

使用示例：

高级配置

环境变量配置

如需固定配置，可创建 .env 文件：

系统服务配置

创建 systemd 服务（Linux）：

🔒 安全特性

v1.1.0+ 版本包含以下安全加固措施：

测试

运行测试套件

配置说明

环境变量

注：环境变量主要用于首次初始化。日常运行中配置通过 Web 管理后台管理，持久化在数据库中。

数据库配置

默认使用 SQLite，数据库文件在首次启动时自动创建：

故障排除

常见问题

1. MCP 连接失败

症状：AI 客户端无法连接到 MCP 服务器

解决方案：

2. API 认证失败

症状：403 Forbidden 或 401 Unauthorized

解决方案：

• 检查管理后台中的 SOAR API 配置是否正确

• 确认 API Token 未过期

• 验证 API 地址是否可达

3. 管理员密码丢失

解决方案：

4. SSL 证书验证失败

症状：内网自签名证书导致 SOAR API 连接失败

解决方案： 在管理后台「系统配置」中将 ssl_verify 设为 False，或在 .env 文件中设置 SSL_VERIFY=0。

5. 服务需要对外暴露

默认情况下服务仅监听 127.0.0.1，如需局域网访问：

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

支持与反馈

• 🐛 问题反馈：GitHub Issues

• 💬 讨论交流：GitHub Discussions

• 📧 邮件联系：support@wuzhi-ai.com

致谢

本项目的MCP服务器实现基于 FastMCP 框架构建。FastMCP 提供了优雅的 Python MCP 服务器开发体验，让我们能够快速构建高质量的 MCP 服务器。感谢 FastMCP 团队的优秀工作！

相关链接

• Model Context Protocol - MCP 官方文档

• FastMCP - Python MCP 服务器框架

• OctoMation Wiki - SOAR 平台文档

• 雾帜智能 - 公司官网

雾帜智能@2025 | 最牛的SOAR | OctoMation

为 AI 赋能网络安全 🔒