Splunk

★ 105

from livehybrid

Interact with Splunk Enterprise/Cloud using natural language queries.

🔥🔥✓ VerifiedAccount requiredAdvanced setup

⚠️ This project is archived — use the official Splunk MCP Server

Thank you to everyone who used, starred, and forked this project! 🙏 It started as a community effort to bring Model Context Protocol (MCP) support to Splunk, well before an official option existed.

Splunk now ships a first-party, fully supported MCP server that has grown beyond what this community project provides. Please migrate to the official server:

📦 Splunk MCP Server on Splunkbase (App 7931, by Splunk LLC): https://splunkbase.splunk.com/app/7931

📖 Docs — MCP Server for Splunk Platform: https://help.splunk.com/en/splunk-cloud-platform/mcp-server-for-splunk-platform/

This repository is now read-only / archived and will no longer receive updates. The code below is preserved for historical reference. Thanks again! 🚀

Splunk MCP (Model Context Protocol) Tool

A FastMCP-based tool for interacting with Splunk Enterprise/Cloud through natural language. This tool provides a set of capabilities for searching Splunk data, managing KV stores, and accessing Splunk resources through an intuitive interface.

Operating Modes

The tool operates in three modes:

SSE Mode (Default)
- Server-Sent Events based communication
- Real-time bidirectional interaction
- Suitable for web-based MCP clients
- Default mode when no arguments provided
- Access via /sse endpoint
API Mode
- RESTful API endpoints
- Access via /api/v1 endpoint prefix
- Start with python splunk_mcp.py api
STDIO Mode
- Standard input/output based communication
- Compatible with Claude Desktop and other MCP clients
- Ideal for direct integration with AI assistants
- Start with python splunk_mcp.py stdio

Features

Splunk Search: Execute Splunk searches with natural language queries
Index Management: List and inspect Splunk indexes
User Management: View and manage Splunk users
KV Store Operations: Create, list, and manage KV store collections
Async Support: Built with async/await patterns for better performance
Detailed Logging: Comprehensive logging with emoji indicators for better visibility
SSL Configuration: Flexible SSL verification options for different security requirements
Enhanced Debugging: Detailed connection and error logging for troubleshooting
Comprehensive Testing: Unit tests covering all major functionality
Error Handling: Robust error handling with appropriate status codes
SSE Compliance: Fully compliant with MCP SSE specification

Available MCP Tools

The following tools are available via the MCP interface:

Tools Management

list_tools
- Lists all available MCP tools with their descriptions and parameters

Health Check

health_check
- Returns a list of available Splunk apps to verify connectivity
ping
- Simple ping endpoint to verify MCP server is alive

User Management

current_user
- Returns information about the currently authenticated user
list_users
- Returns a list of all users and their roles

Index Management

list_indexes
- Returns a list of all accessible Splunk indexes
get_index_info
- Returns detailed information about a specific index
- Parameters: index_name (string)
indexes_and_sourcetypes
- Returns a comprehensive list of indexes and their sourcetypes

Search

search_splunk
- Executes a Splunk search query
- Parameters:
  - search_query (string): Splunk search string
  - earliest_time (string, optional): Start time for search window
  - latest_time (string, optional): End time for search window
  - max_results (integer, optional): Maximum number of results to return
list_saved_searches
- Returns a list of saved searches in the Splunk instance

KV Store

list_kvstore_collections
- Lists all KV store collections
create_kvstore_collection
- Creates a new KV store collection
- Parameters: collection_name (string)
delete_kvstore_collection
- Deletes an existing KV store collection
- Parameters: collection_name (string)

SSE Endpoints

When running in SSE mode, the following endpoints are available:

/sse: Returns SSE connection information in text/event-stream format
- Provides metadata about the SSE connection
- Includes URL for the messages endpoint
- Provides protocol and capability information
/sse/messages: The main SSE stream endpoint
- Streams system events like heartbeats
- Maintains persistent connection
- Sends properly formatted SSE events
/sse/health: Health check endpoint for SSE mode
- Returns status and version information in SSE format

Error Handling

The MCP implementation includes consistent error handling:

Invalid search commands or malformed requests
Insufficient permissions
Resource not found
Invalid input validation
Unexpected server errors
Connection issues with Splunk server

All error responses include a detailed message explaining the error.

Operating Modes

The tool operates in three modes:

SSE Mode (Default)
- Server-Sent Events based communication
- Real-time bidirectional interaction
- Suitable for web-based MCP clients
- Default mode when no arguments provided
- Access via /sse endpoint
API Mode
- RESTful API endpoints
- Access via /api/v1 endpoint prefix
- Start with python splunk_mcp.py api
STDIO Mode
- Standard input/output based communication
- Compatible with Claude Desktop and other MCP clients
- Ideal for direct integration with AI assistants
- Start with python splunk_mcp.py stdio

Environment Variables

Configure the following environment variables:

SPLUNK_HOST: Your Splunk host address
SPLUNK_PORT: Splunk management port (default: 8089)
SPLUNK_USERNAME: Your Splunk username
SPLUNK_PASSWORD: Your Splunk password
SPLUNK_TOKEN: (Optional) Splunk authentication token. If set, this will be used instead of username/password.
SPLUNK_SCHEME: Connection scheme (default: https)
VERIFY_SSL: Enable/disable SSL verification (default: true)
FASTMCP_LOG_LEVEL: Logging level (default: INFO)
SERVER_MODE: Server mode (sse, api, stdio) when using uvicorn

SSL Configuration

The tool provides flexible SSL verification options:

Default (Secure) Mode:

Copy & paste — that's it

VERIFY_SSL=true

Full SSL certificate verification
Hostname verification enabled
Recommended for production environments

Relaxed Mode:

Copy & paste — that's it

VERIFY_SSL=false

SSL certificate verification disabled
Hostname verification disabled
Useful for testing or self-signed certificates

Testing

The project includes comprehensive test coverage using pytest and end-to-end testing with a custom MCP client:

Running Tests

Basic test execution:

Copy & paste — that's it

poetry run pytest

With coverage reporting:

Copy & paste — that's it

poetry run pytest --cov=splunk_mcp

Copy & paste — that's it

# Install main dependencies
uv sync

# Or install with development dependencies
uv sync --extra dev

Before it works, you'll need: SPLUNK_TOKEN

Installation

Using UV (Recommended)

UV is a fast Python package installer and resolver, written in Rust. It's significantly faster than pip and provides better dependency resolution.

Prerequisites

Python 3.10 or higher
UV installed (see UV installation guide)

Quick Start with UV

Clone the repository:
Copy & paste — that's it
```
git clone <repository-url>
cd splunk-mcp
```

Install dependencies with UV:

Copy & paste — that's it

# Install main dependencies
uv sync

# Or install with development dependencies
uv sync --extra dev

Run the application:

Copy & paste — that's it

# SSE mode (default)
uv run python splunk_mcp.py

# STDIO mode
uv run python splunk_mcp.py stdio

# API mode
uv run python splunk_mcp.py api

UV Commands Reference

Copy & paste — that's it

# Install dependencies
uv sync

# Install with development dependencies
uv sync --extra dev

# Run the application
uv run python splunk_mcp.py

# Run tests
uv run pytest

# Run with specific Python version
uv run --python 3.11 python splunk_mcp.py

# Add a new dependency
uv add fastapi

# Add a development dependency
uv add --dev pytest

# Update dependencies
uv sync --upgrade

# Generate requirements.txt
uv pip compile pyproject.toml -o requirements.txt

Using Poetry (Alternative)

If you prefer Poetry, you can still use it:

Copy & paste — that's it

# Install dependencies
poetry install

# Run the application
poetry run python splunk_mcp.py

Using pip (Alternative)

Copy & paste — that's it

# Install dependencies
pip install -r requirements.txt

# Run the application
python splunk_mcp.py

Usage

Local Usage

The tool can run in three modes:

SSE mode (default for MCP clients):

Copy & paste — that's it

# 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

STDIO mode:

Copy & paste — that's it

poetry run python splunk_mcp.py stdio

Docker Usage

The project supports both the new docker compose (V2) and legacy docker-compose (V1) commands. The examples below use V2 syntax, but both are supported.

SSE Mode (Default):

Copy & paste — that's it

docker compose up -d mcp

API Mode:

Copy & paste — that's it

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

STDIO Mode:

Copy & paste — that's it

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

Testing with Docker

The project includes a dedicated test environment in Docker:

Run all tests:

Copy & paste — that's it

./run_tests.sh --docker

Run specific test components:

Copy & paste — that's it

# 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 will be available in the ./test-results directory.

Docker Development Tips

Building Images:

Copy & paste — that's it

# Build both images
docker compose build

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

Viewing Logs:

Copy & paste — that's it

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

Debugging:

Copy & paste — that's it

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

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

Note: If you're using Docker Compose V1, replace docker compose with docker-compose in the above commands.

Security Notes

Environment Variables:

Never commit .env files
Use .env.example as a template
Consider using Docker secrets for production

SSL Verification:

VERIFY_SSL=true recommended for production
Can be disabled for development/testing
Configure through environment variables

Port Exposure:

Only expose necessary ports
Use internal Docker network when possible
Consider network security in production