首页/监控工具/splunk-mcp

splunk-mcp

查看源码
livehybrid
2025-5-11
Words 2972Read Time≈ 8 min
Score:90

用于Splunk Enterprise/Cloud的MCP服务器，支持通过自然语言查询Splunk数据，管理KV存储和用户。

MCP服务器
Python

Splunk MCP (Model Context Protocol) 工具

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

操作模式

该工具支持三种操作模式：
  1. SSE 模式（默认）
      • 基于 Server-Sent Events 的通信
      • 实时双向交互
      • 适用于基于 Web 的 MCP 客户端
      • 未提供参数时默认启用此模式
      • 通过 /sse 端点访问
  1. API 模式
      • RESTful API 端点
      • 通过 /api/v1 端点前缀访问
      • 使用 python splunk_mcp.py api 启动
  1. STDIO 模式
      • 基于标准输入/输出的通信
      • 兼容 Claude Desktop 和其他 MCP 客户端
      • 适合直接与 AI 助手集成
      • 使用 python splunk_mcp.py stdio 启动

功能特性

  • Splunk 搜索：通过自然语言查询执行 Splunk 搜索
  • 索引管理：列出和检查 Splunk 索引
  • 用户管理：查看和管理 Splunk 用户
  • KV 存储操作：创建、列出和管理 KV 存储集合
  • 异步支持：基于 async/await 模式构建，性能更优
  • 详细日志：带有表情符号指示的全面日志记录，提升可见性
  • SSL 配置：灵活的 SSL 验证选项，满足不同安全需求
  • 增强调试：详细的连接和错误日志，便于故障排除
  • 全面测试：涵盖所有主要功能的单元测试
  • 错误处理：健壮的错误处理机制，返回适当的状态码
  • SSE 合规性：完全符合 MCP SSE 规范

可用的 MCP 工具

通过 MCP 接口可访问以下工具：

工具管理

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

健康检查

  • health_check
    • 返回可用的 Splunk 应用列表，用于验证连接性
  • ping
    • 简单的 ping 端点，用于验证 MCP 服务器是否存活

用户管理

  • current_user
    • 返回当前认证用户的信息
  • list_users
    • 返回所有用户及其角色的列表

索引管理

  • list_indexes
    • 返回所有可访问的 Splunk 索引列表
  • get_index_info
    • 返回特定索引的详细信息
    • 参数：index_name (字符串)
  • indexes_and_sourcetypes
    • 返回索引及其 sourcetypes 的全面列表

搜索

  • search_splunk
    • 执行 Splunk 搜索查询
    • 参数：
      • search_query (字符串)：Splunk 搜索字符串
      • earliest_time (字符串, 可选)：搜索窗口的开始时间
      • latest_time (字符串, 可选)：搜索窗口的结束时间
      • max_results (整数, 可选)：返回的最大结果数
  • list_saved_searches
    • 返回 Splunk 实例中保存的搜索列表

KV 存储

  • list_kvstore_collections
    • 列出所有 KV 存储集合
  • create_kvstore_collection
    • 创建新的 KV 存储集合
    • 参数：collection_name (字符串)
  • delete_kvstore_collection
    • 删除现有的 KV 存储集合
    • 参数：collection_name (字符串)

SSE 端点

在 SSE 模式下运行时，以下端点可用：
  • /sse：以 text/event-stream 格式返回 SSE 连接信息
    • 提供 SSE 连接的元数据
    • 包含消息端点的 URL
    • 提供协议和功能信息
  • /sse/messages：主要的 SSE 流端点
    • 流式传输系统事件（如心跳）
    • 保持持久连接
    • 发送格式正确的 SSE 事件
  • /sse/health：SSE 模式的健康检查端点
    • 以 SSE 格式返回状态和版本信息

错误处理

MCP 实现包括一致的错误处理：
  • 无效的搜索命令或格式错误的请求
  • 权限不足
  • 资源未找到
  • 无效的输入验证
  • 意外的服务器错误
  • 与 Splunk 服务器的连接问题
所有错误响应均包含详细的消息，解释错误原因。

先决条件

  • Python 3.10 或更高版本
  • 用于依赖管理的 Poetry
  • Splunk Enterprise/Cloud 实例
  • 具有必要权限的 Splunk 凭据

安装

选项 1：本地安装

  1. 克隆仓库：
  1. 使用 Poetry 安装依赖：
  1. 复制示例环境文件并配置您的设置：
  1. 更新 .env 文件中的 Splunk 凭据：

选项 2：Docker 安装

  1. 拉取最新镜像：
  1. 如上所述创建 .env 文件，或直接使用环境变量。
  1. 使用 Docker Compose 运行：
或直接使用 Docker：

使用

本地使用

该工具可以在三种模式下运行：
  1. SSE 模式（MCP 客户端的默认模式）：
  1. STDIO 模式：

Docker 使用

该项目支持新的 docker compose (V2) 和旧的 docker-compose (V1) 命令。以下示例使用 V2 语法，但两者都支持。
  1. SSE 模式（默认）：
  1. API 模式：
  1. STDIO 模式：

使用 Docker 测试

该项目在 Docker 中包含一个专用的测试环境：
  1. 运行所有测试：
  1. 运行特定测试组件：
测试结果将保存在 ./test-results 目录中。

Docker 开发提示

  1. 构建镜像：
  1. 查看日志：
  1. 调试：
注意：如果使用 Docker Compose V1，请将上述命令中的 docker compose 替换为 docker-compose。

安全注意事项

  1. 环境变量：
  • 切勿提交 .env 文件
  • 使用 .env.example 作为模板
  • 在生产环境中考虑使用 Docker 密钥
  1. SSL 验证：
  • 建议在生产环境中使用 VERIFY_SSL=true
  • 可在开发/测试中禁用
  • 通过环境变量配置
  1. 端口暴露：
  • 仅暴露必要的端口
  • 尽可能使用内部 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：服务器模式（sse, api, stdio），使用 uvicorn 时指定

SSL 配置

该工具提供灵活的 SSL 验证选项：
  1. 默认（安全）模式：
  • 完全 SSL 证书验证
  • 启用主机名验证
  • 推荐用于生产环境
  1. 宽松模式：
  • 禁用 SSL 证书验证
  • 禁用主机名验证
  • 适用于测试或自签名证书

测试

该项目使用 pytest 和自定义 MCP 客户端进行端到端测试，提供了全面的测试覆盖：

运行测试

基本测试执行：
带覆盖率报告：
带详细输出：

端到端 SSE 测试

该项目包含一个自定义 MCP 客户端测试脚本，用于连接到实时 SSE 端点并测试所有工具：
该脚本作为 MCP 客户端执行以下操作：
  1. 连接到 /sse 端点以获取消息 URL
  1. 向消息端点发送工具调用
  1. 处理 SSE 事件以提取工具结果
  1. 根据预期格式验证结果
这提供了对 SSE 接口的真实测试，与实际 MCP 客户端的使用方式一致。

测试结构

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

测试工具

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

故障排除

连接问题

  1. 基本连接性：
  • 该工具现在执行基本的 TCP 连接性测试
  • 检查端口 8089 是否可访问
  • 验证网络路由和防火墙设置
  1. SSL 问题：
  • 如果遇到 SSL 错误，尝试设置 VERIFY_SSL=false
  • 检查证书的有效性和信任链
  • 验证主机名是否与证书匹配
  1. 认证问题：
  • 验证 Splunk 凭据
  • 检查用户权限
  • 确保账户未被锁定
  1. 调试：
  • 设置 FASTMCP_LOG_LEVEL=DEBUG 以获取详细日志
  • 检查连接日志中的具体错误消息
  • 查看 SSL 配置消息
  1. SSE 连接问题：
  • 验证 /sse 端点是否可访问
  • 检查正确的内容类型头
  • 使用浏览器开发者工具检查 SSE 连接

Claude 集成

Claude Desktop 配置

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

STDIO 模式（推荐用于桌面）

SSE 模式

与 Claude 一起使用

配置完成后，您可以通过自然语言与 Splunk 进行交互。例如：
  1. 列出可用索引：
  1. 搜索 Splunk 数据：
  1. 获取系统健康状态：
  1. 管理 KV 存储：
MCP 工具将自动对 Claude 可用，使其能够通过自然语言命令执行这些操作。

许可证

[您的许可证]

致谢

  • FastMCP 框架
  • Splunk SDK for Python
  • Python-decouple 用于配置管理
  • SSE Starlette 用于 SSE 实现
上一篇
mcp-thought-server
下一篇
mcp-dataverse
Catalog