Splunk Mcp

> # ⚠️ 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:

1. 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

1. API Mode

• RESTful API endpoints
• Access via /api/v1 endpoint prefix
• Start with python splunk_mcp.py api

1. 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
• getindexinfo
• Returns detailed information about a specific index
• Parameters: index_name (string)
• indexesandsourcetypes
• 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
• listsavedsearches
• Returns a list of saved searches in the Splunk instance

KV Store

• listkvstorecollections
• Lists all KV store collections
• createkvstorecollection
• Creates a new KV store collection
• Parameters: collection_name (string)
• deletekvstorecollection
• 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.

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

1. Clone the repository:

``bash git clone cd splunk-mcp ``

1. Install dependencies with UV:

```bash # Install main dependencies uv sync

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

1. Run the application:

```bash # 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

# 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:

# Install dependencies
poetry install

# Run the application
poetry run python splunk_mcp.py

Using pip (Alternative)

# Install dependencies
pip install -r requirements.txt

# Run the application
python splunk_mcp.py

Operating Modes

The tool operates in three modes:

1. 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

1. API Mode

• RESTful API endpoints
• Access via /api/v1 endpoint prefix
• Start with python splunk_mcp.py api

1. 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

Usage

Local Usage

The tool can run in three modes:

1. SSE mode (default for MCP clients):

# 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 mode:

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.

1. SSE Mode (Default):

docker compose up -d mcp

1. API Mode:

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

1. STDIO Mode:

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

Testing with Docker

The project includes a dedicated test environment in Docker:

1. Run all tests:

./run_tests.sh --docker

1. Run specific test components:

# 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

1. Building Images:

# Build both images
docker compose build

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

1. Viewing Logs:

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

1. Debugging:

# 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

1. Environment Variables:

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

1. SSL Verification:

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

1. Port Exposure:

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

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:

1. Default (Secure) Mode:

VERIFY_SSL=true

• Full SSL certificate verification
• Hostname verification enabled
• Recommended for production environments

1. Relaxed Mode:

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:

poetry run pytest

With coverage reporting:

poetry run pytest --cov=splunk_mcp

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: livehybrid
• Source: livehybrid/splunk-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.