Splunk MCP (Model Context Protocol) 工具

基于 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 客户端
   • 适合直接与 AI 助手集成
   • 启动命令：python splunk_mcp.py stdio

功能

• Splunk 搜索：使用自然语言查询执行 Splunk 搜索
• 索引管理：列出和检查 Splunk 索引
• 用户管理：查看和管理 Splunk 用户
• KV 存储操作：创建、列出和管理 KV 存储集合
• 异步支持：使用 async/await 模式构建，以提高性能
• 详细日志记录：带有表情符号指示符的全面日志记录，以便更好地可视化
• SSL 配置：灵活的 SSL 验证选项，满足不同的安全需求
• 增强调试：详细的连接和错误日志记录，便于故障排除
• 全面测试：涵盖所有主要功能的单元测试
• 错误处理：健壮的错误处理，并附带适当的 HTTP 状态码
• 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
  • 返回索引及其来源类型的综合列表

搜索

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

KV Store

• 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

1. 使用 Poetry 安装依赖项：

poetry install

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

cp .env.example .env

1. 更新 .env 文件以包含您的 Splunk 凭证：

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

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

2. 使用 Docker Compose 运行：

docker-compose up -d

或者直接使用 Docker：

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

使用

本地使用

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

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

# Start in SSE mode (default)
poetry run python splunk_mcp.py
# or explicitly:
poetry run python splunk_mcp.py sse

# Use uvicorn directly:
SERVER_MODE=api poetry run uvicorn splunk_mcp:app --host 0.0.0.0 --port 8000 --reload

1. STDIO 模式：

poetry run python splunk_mcp.py stdio

Docker 使用

该项目支持新的 docker compose（V2）和旧版 docker-compose（V1）命令。下面的例子使用 V2 语法，但两者都支持。

1. SSE 模式（默认）：

docker compose up -d mcp

1. API 模式：

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

1. STDIO 模式：

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

使用 Docker 进行测试

项目包括一个专门的 Docker 测试环境：

1. 运行所有测试：

./run_tests.sh --docker

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

# Run only the MCP server
docker compose up -d mcp

# Run only the test container
docker compose up test

# Run both with test results
docker compose up --abort-on-container-exit

测试结果将存放在 ./test-results 目录中。

Docker 开发技巧

1. 构建镜像:

# Build both images
docker compose build

# Build specific service
docker compose build mcp
docker compose build test

1. 查看日志:

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

1. 调试:

# Run with debug mode
DEBUG=true docker compose up mcp

# Access container shell
docker compose exec mcp /bin/bash

注意：如果你使用的是 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: 使用 uvicorn 时的服务器模式（sse, api, stdio）

SSL 配置

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

1. 默认（安全）模式:

VERIFY_SSL=true

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

1. 宽松模式:

VERIFY_SSL=false

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

测试

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

运行测试

基本测试执行：

poetry run pytest

带有覆盖率报告：

poetry run pytest --cov=splunk_mcp

详细输出：

poetry run pytest -v

端到端 SSE 测试

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

# Test all tools
python test_endpoints.py

# Test specific tools
python test_endpoints.py health_check list_indexes

# List all available tools
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 是否可访问
• 验证网络路由和防火墙

1. SSL 问题：

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

1. 身份验证问题：

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

1. 调试：

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

1. SSE 连接问题：

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

Claude 集成

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?

1. 搜索 Splunk 数据：

Search Splunk for failed login attempts in the last 24 hours

1. 获取系统健康状况：

Check the health of the Splunk system

1. 管理 KV 存储：

List all KV store collections

MCP 工具将自动对 Claude 可用，使其能够通过自然语言命令执行这些操作。

许可证

[您的许可证在这里]

致谢

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