splunk-mcp

Splunk MCP（模型上下文协议）工具

基于 FastMCP 的工具，用于通过自然语言与 Splunk Enterprise/Cloud 交互。该工具提供了一系列功能，用于通过直观的界面搜索 Splunk 数据、管理 KV 存储以及访问 Splunk 资源。

操作模式

该工具有三种运行模式：

1. SSE 模式（默认）
   • 基于服务器发送事件的通信
   • 实时双向互动
   • 适用于基于 Web 的 MCP 客户端
   • 未提供参数时的默认模式
   • 通过/sse端点访问
2. API模式
   • RESTful API 端点
   • 通过/api/v1端点前缀访问
   • 从python splunk_mcp.py api开始
3. STDIO模式
   • 基于标准输入/输出的通信
   • 与 Claude Desktop 和其他 MCP 客户端兼容
   • 非常适合与人工智能助手直接集成
   • 从python splunk_mcp.py stdio开始

特征

• Splunk 搜索：使用自然语言查询执行 Splunk 搜索
• 索引管理：列出并检查 Splunk 索引
• 用户管理：查看和管理 Splunk 用户
• KV 商店操作：创建、列出和管理 KV 商店集合
• 异步支持：采用异步/等待模式构建，以获得更好的性能
• 详细日志：使用表情符号指示器进行全面日志记录，以获得更好的可视性
• SSL 配置：灵活的 SSL 验证选项，满足不同的安全要求
• 增强的调试：详细的连接和错误日志，用于故障排除
• 全面测试：单元测试涵盖所有主要功能
• 错误处理：使用适当的状态代码进行强大的错误处理
• SSE 合规性：完全符合 MCP SSE 规范

可用的 MCP 工具

可通过 MCP 界面使用以下工具：

工具管理

• 列表工具
  • 列出所有可用的 MCP 工具及其描述和参数

健康检查

• 健康检查
  • 返回可用 Splunk 应用程序列表以验证连接性
• ping
  • 简单 ping 端点来验证 MCP 服务器是否处于活动状态

用户管理

• 当前用户
  • 返回有关当前已验证用户的信息
• 列出用户
  • 返回所有用户及其角色的列表

指数管理

• 列表索引
  • 返回所有可访问的 Splunk 索引的列表
• 获取索引信息
  • 返回有关特定索引的详细信息
  • 参数：index_name（字符串）
• 索引和源类型
  • 返回索引及其源类型的完整列表

搜索

• 搜索_splunk
  • 执行 Splunk 搜索查询
  • 参数：
    • search_query（字符串）：Splunk 搜索字符串
    • 最早的时间（字符串，可选）：搜索窗口的开始时间
    • latest_time（字符串，可选）：搜索窗口的结束时间
    • max_results（整数，可选）：返回的最大结果数
• 列出已保存的搜索
  • 返回 Splunk 实例中已保存的搜索列表

KV商店

• 列表_kvstore_collections
  • 列出所有 KV 商店集合
• 创建_kvstore_collection
  • 创建一个新的 KV 存储集合
  • 参数：collection_name（字符串）
• 删除_kvstore_collection
  • 删除现有的 KV 存储集合
  • 参数：collection_name（字符串）

SSE 终端节点

在 SSE 模式下运行时，以下端点可用：

• /sse ：以文本/事件流格式返回 SSE 连接信息
  • 提供有关 SSE 连接的元数据
  • 包含消息端点的 URL
  • 提供协议和功能信息
• /sse/messages ：主 SSE 流端点
  • 流式传输心跳等系统事件
  • 保持持久连接
  • 发送格式正确的 SSE 事件
• /sse/health ：SSE 模式的健康检查端点
  • 以 SSE 格式返回状态和版本信息

错误处理

MCP 实现包括一致的错误处理：

• 无效的搜索命令或格式错误的请求
• 权限不足
• 未找到资源
• 输入验证无效
• 意外的服务器错误
• Splunk 服务器连接问题

所有错误响应都包含一条解释错误的详细消息。

先决条件

• Python 3.10 或更高版本
• 依赖管理的诗歌
• Splunk Enterprise/云实例
• 具有必要权限的适当 Splunk 凭证

安装

选项 1：本地安装

1. 克隆存储库：

2. 使用 Poetry 安装依赖项：

3. 复制示例环境文件并配置您的设置：

4. 使用您的 Splunk 凭证更新.env文件：

选项 2：Docker 安装

1. 拉取最新镜像：

2. 按照上述方法创建.env文件或直接使用环境变量。
3. 使用 Docker Compose 运行：

或者直接使用 Docker：

用法

本地使用

该工具可以以三种模式运行：

1. SSE 模式（MCP 客户端的默认模式）：

3. STDIO模式：

Docker 使用

该项目同时支持新版docker compose (V2) 和旧版docker-compose (V1) 命令。以下示例使用的是 V2 语法，但两种语法均受支持。

1. SSE 模式（默认）：

2. API模式：

3. STDIO模式：

使用 Docker 进行测试

该项目包含 Docker 中的专用测试环境：

1. 运行所有测试：

2. 运行特定的测试组件：

测试结果将在./test-results目录中提供。

Docker 开发技巧

1. 建筑图像：

2. 查看日志：

3. 调试：

注意：如果您使用的是 Docker Compose V1，请将上述命令中的docker compose替换为docker-compose 。

安全说明

1. 环境变量：

• 永远不要提交.env文件
• 使用.env.example作为模板
• 考虑在生产中使用 Docker secrets

2. SSL验证：

• 建议在生产环境中使用VERIFY_SSL=true
• 可以禁用以进行开发/测试
• 通过环境变量配置

3. 端口暴露：

• 只暴露必要的端口
• 尽可能使用内部 Docker 网络
• 在生产中考虑网络安全

环境变量

配置以下环境变量：

• SPLUNK_HOST ：您的 Splunk 主机地址
• SPLUNK_PORT ：Splunk 管理端口（默认值：8089）
• SPLUNK_USERNAME ：您的 Splunk 用户名
• SPLUNK_PASSWORD ：您的 Splunk 密码
• SPLUNK_SCHEME ：连接方案（默认值：https）
• VERIFY_SSL ：启用/禁用 SSL 验证（默认值：true）
• FASTMCP_LOG_LEVEL ：日志记录级别（默认值：INFO）
• SERVER_MODE ：使用 uvicorn 时的服务器模式（sse、api、stdio）

SSL 配置

该工具提供了灵活的 SSL 验证选项：

1. 默认（安全）模式：

• 完整的 SSL 证书验证
• 已启用主机名验证
• 推荐用于生产环境

2. 轻松模式：

• SSL 证书验证已禁用
• 已禁用主机名验证
• 适用于测试或自签名证书

测试

该项目包括使用 pytest 进行全面测试覆盖以及使用自定义 MCP 客户端进行端到端测试：

运行测试

基本测试执行：

覆盖范围报告：

详细输出：

端到端 SSE 测试

该项目包括一个自定义的 MCP 客户端测试脚本，该脚本连接到实时 SSE 端点并测试所有工具：

该脚本通过以下方式充当 MCP 客户端：

1. 连接到/sse端点以获取消息 URL
2. 将工具调用发送到消息端点
3. 处理 SSE 事件以提取工具结果
4. 根据预期格式验证结果

这为 SSE 接口提供了真实世界的测试，因为它将被实际的 MCP 客户端使用。

测试结构

该项目采用三种互补的测试方法：

1. MCP 集成测试（ tests/test_api.py ） ：
   • 通过mcp.call_tool()测试 MCP 工具接口
   • 使用 FastMCP 验证工具注册是否正确
   • 确保正确的响应格式和数据结构
   • 验证 MCP 接口级别的错误处理
   • **注意：**理想情况下，应将此文件重命名为test_mcp.py ，以更好地反映其用途
2. 直接功能测试（ tests/test_endpoints_pytest.py ） ：
   • 直接测试 Splunk 功能（绕过 MCP 层）
   • 提供更全面的功能实现细节
   • 测试边缘情况、参数变化和错误处理
   • 包括 SSL 配置、连接参数和超时测试
   • 使用参数化测试实现高效的测试覆盖
3. 端到端 MCP 客户端测试（ test_endpoints.py ） ：
   • 行为类似于连接到 SSE 端点的真实 MCP 客户端
   • 测试从连接到工具调用到响应解析的完整流程
   • 验证实际的 SSE 协议实现
   • 使用真实参数针对实时服务器测试工具
4. 配置测试（ tests/test_config.py ） ：
   • 环境变量解析测试
   • SSL 验证设置
   • 连接参数验证

测试工具

测试支持：

• 使用 pytest-asyncio 进行异步测试
• 使用 pytest-cov 进行覆盖率报告
• 使用 pytest-mock 进行模拟
• 参数化测试
• 连接超时测试

故障排除

连接问题

1. 基本连接：

• 该工具现在执行基本的 TCP 连接测试
• 检查8089端口是否可以访问
• 验证网络路由和防火墙

2. SSL 问题：

• 如果看到 SSL 错误，请尝试设置VERIFY_SSL=false
• 检查证书有效性和信任链
• 验证主机名是否与证书匹配

3. 身份验证问题：

• 验证 Splunk 凭证
• 检查用户权限
• 确保帐户未被锁定

4. 调试：

• 设置FASTMCP_LOG_LEVEL=DEBUG获取详细日志
• 检查连接日志中的具体错误消息
• 查看 SSL 配置消息

5. SSE 连接问题：

• 验证是否可以通过/sse访问 SSE 端点
• 检查正确的内容类型标头
• 使用浏览器开发者工具检查 SSE 连接

克劳德积分

Claude桌面配置

您可以通过将 Splunk MCP 配置为使用 SSE 或 STDIO 模式来将其与 Claude Desktop 集成。将以下配置添加到claude_desktop_config.json文件中：

STDIO 模式（推荐用于桌面）

SSE模式

与 Claude 一起使用

配置完成后，您可以通过 Claude 使用自然语言与 Splunk 进行交互。示例：

1. 列出可用索引：

2. 搜索 Splunk 数据：

3. 获取系统健康：

4. 管理 KV 存储：

MCP 工具将自动供 Claude 使用，允许它通过自然语言命令执行这些操作。

执照

[此处为您的许可证]

致谢

• FastMCP 框架
• 适用于 Python 的 Splunk SDK
• Python-decouple 用于配置管理
• SSE Starlette 用于 SSE 实施