Splunk MCP (模型上下文协议) 工具

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

运行模式

该工具以三种模式运行：

1. SSE 模式 (默认)

   • 基于服务器发送事件 (Server-Sent Events) 的通信
   • 实时双向交互
   • 适用于基于 Web 的 MCP 客户端
   • 未提供参数时的默认模式
   • 通过 /sse 端点访问

2. API 模式

   • RESTful API 端点
   • 通过 /api/v1 端点前缀访问
   • 使用 python splunk_mcp.py api 启动

3. 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
  • 返回索引及其 sourcetype 的综合列表

搜索

• 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. 克隆存储库：

git clone <repository-url>
cd splunk-mcp

2. 使用 Poetry 安装依赖项：

poetry install

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

cp .env.example .env

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

SPLUNK_HOST=your_splunk_host
SPLUNK_PORT=8089
SPLUNK_USERNAME=your_username
SPLUNK_PASSWORD=your_password
SPLUNK_SCHEME=https
VERIFY_SSL=true
FASTMCP_LOG_LEVEL=INFO

选项 2：Docker 安装

1. 拉取最新镜像：

docker pull livehybrid/splunk-mcp:latest

2. 如上所述创建您的 .env 文件，或直接使用环境变量。

3. 使用 Docker Compose 运行：

docker-compose up -d

或者直接使用 Docker 运行：

docker run -i \
  --env-file .env \
  livehybrid/splunk-mcp

用法

本地用法

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

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

# 以 SSE 模式启动（默认）
poetry run python splunk_mcp.py
# 或显式指定：
poetry run python splunk_mcp.py sse

# 直接使用 uvicorn：
SERVER_MODE=api poetry run uvicorn splunk_mcp:app --host 0.0.0.0 --port 8000 --reload

3. STDIO 模式：

poetry run python splunk_mcp.py stdio

Docker 用法

该项目支持新的 docker compose (V2) 和旧的 docker-compose (V1) 命令。 以下示例使用 V2 语法，但两者都支持。

1. SSE 模式（默认）：

docker compose up -d mcp

2. API 模式：

docker compose run --rm mcp python splunk_mcp.py api

3. STDIO 模式：

docker compose run -i --rm mcp python splunk_mcp.py stdio

使用 Docker 进行测试

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

1. 运行所有测试：

./run_tests.sh --docker

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

# 仅运行 MCP 服务器
docker compose up -d mcp

# 仅运行测试容器
docker compose up test

# 运行两者并显示测试结果
docker compose up --abort-on-container-exit

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

Docker 开发技巧

1. 构建镜像:

# 构建两个镜像
docker compose build

# 构建特定服务
docker compose build mcp
docker compose build test

2. 查看日志:

# 查看所有日志
docker compose logs

# 跟踪特定服务日志
docker compose logs -f mcp

3. 调试:

# 以调试模式运行
DEBUG=true docker compose up mcp

# 访问容器 shell
docker compose exec mcp /bin/bash

注意：如果您使用的是 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. 默认（安全）模式:

VERIFY_SSL=true

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

2. 宽松模式:

VERIFY_SSL=false

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

测试

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

运行测试

基本测试执行：

poetry run pytest

带有覆盖率报告：

poetry run pytest --cov=splunk_mcp

带有详细输出：

poetry run pytest -v

端到端 SSE 测试

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

# 测试所有工具
python test_endpoints.py

# 测试特定工具
python test_endpoints.py health_check list_indexes

# 列出所有可用工具
python test_endpoints.py --list

此脚本充当 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):

   • 表现得像一个真正的 MCP 客户端，连接到 SSE 端点
   • 测试从连接到工具调用到响应解析的完整流程
   • 验证实际的 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 集成

Claude Desktop 配置

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

STDIO 模式（推荐用于桌面）

{
  "splunk": {
    "command": "poetry",
    "env": {
      "SPLUNK_HOST": "your_splunk_host",
      "SPLUNK_PORT": "8089",
      "SPLUNK_USERNAME": "your_username",
      "SPLUNK_PASSWORD": "your_password",
      "SPLUNK_SCHEME": "https",
      "VERIFY_SSL": "false"
    },
    "args": ["--directory", "/path/to/splunk-mcp", "run", "splunk_mcp.py", "stdio"]
  }
}

SSE 模式

{
  "splunk": {
    "command": "poetry",
    "env": {
      "SPLUNK_HOST": "your_splunk_host",
      "SPLUNK_PORT": "8089",
      "SPLUNK_USERNAME": "your_username",
      "SPLUNK_PASSWORD": "your_password",
      "SPLUNK_SCHEME": "https",
      "VERIFY_SSL": "false",
      "FASTMCP_PORT": "8001",
      "DEBUG": "true"
    },
    "args": ["--directory", "/path/to/splunk-mcp", "run", "splunk_mcp.py", "sse"]
  }
}

与 Claude 一起使用

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

1. 列出可用的索引：

What Splunk indexes are available?

2. 搜索 Splunk 数据：

Search Splunk for failed login attempts in the last 24 hours

3. 获取系统健康状况：

Check the health of the Splunk system

4. 管理 KV 存储：

List all KV store collections

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

许可证

[您的许可证]

鸣谢

• FastMCP 框架
• Splunk SDK for Python
• Python-decouple 用于配置管理
• SSE Starlette 用于 SSE 实现