splunk mcp mcp server| gluon mcp

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.

Prerequisites

Python 3.10 or higher
Poetry for dependency management
Splunk Enterprise/Cloud instance
Appropriate Splunk credentials with necessary permissions

Installation

Option 1: Local Installation

Clone the repository:

git clone <repository-url>
cd splunk-mcp

Install dependencies using Poetry:
```
poetry install
```
Copy the example environment file and configure your settings:
```
cp .env.example .env
```

Update the .env file with your Splunk credentials:

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

Option 2: Docker Installation

Pull the latest image:

docker pull livehybrid/splunk-mcp:latest

Create your .env file as above or use environment variables directly.
Run using Docker Compose:
```
docker-compose up -d
```

Or using Docker directly:

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

Usage

Local Usage

The tool can run in three modes:

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

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.

SSE Mode (Default):
```
docker compose up -d mcp
```

API Mode:

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

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:

Run all tests:
```
./run_tests.sh --docker
```

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

Building Images:

# Build both images
docker compose build

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

Viewing Logs:

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

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

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

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_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:
```
VERIFY_SSL=true
```
Full SSL certificate verification
Hostname verification enabled
Recommended for production environments
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

With verbose output:

poetry run pytest -v

End-to-End SSE Testing

The project includes a custom MCP client test script that connects to the live SSE endpoint and tests all tools:

# 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

This script acts as an MCP client by: 1. Connecting to the /sse endpoint to get the messages URL 2. Sending tool invocations to the messages endpoint 3. Processing the SSE events to extract tool results 4. Validating the results against expected formats

This provides real-world testing of the SSE interface as it would be used by an actual MCP client.

Test Structure

The project uses three complementary testing approaches:

MCP Integration Tests (tests/test_api.py):
Tests the MCP tools interface through mcp.call_tool()
Verifies proper tool registration with FastMCP
Ensures correct response format and data structure
Validates error handling at the MCP interface level
Note: This file should ideally be renamed to test_mcp.py to better reflect its purpose
Direct Function Tests (tests/test_endpoints_pytest.py):
Tests Splunk functions directly (bypassing the MCP layer)
Provides more comprehensive coverage of function implementation details
Tests edge cases, parameter variations, and error handling
Includes tests for SSL configuration, connection parameters, and timeouts
Uses parameterized testing for efficient test coverage
End-to-End MCP Client Tests (test_endpoints.py):
Behaves like a real MCP client connecting to the SSE endpoint
Tests the complete flow from connection to tool invocation to response parsing
Validates the actual SSE protocol implementation
Tests tools with real parameters against the live server
Configuration Tests (tests/test_config.py):
Tests for environment variable parsing
SSL verification settings
Connection parameter validation

Testing Tools

The tests support: - Async testing with pytest-asyncio - Coverage reporting with pytest-cov - Mocking with pytest-mock - Parameterized testing - Connection timeout testing

Troubleshooting

Connection Issues

Basic Connectivity:
The tool now performs a basic TCP connectivity test
Check if port 8089 is accessible
Verify network routing and firewalls
SSL Issues:
If seeing SSL errors, try setting VERIFY_SSL=false
Check certificate validity and trust chain
Verify hostname matches certificate
Authentication Issues:
Verify Splunk credentials
Check user permissions
Ensure account is not locked
Debugging:
Set FASTMCP_LOG_LEVEL=DEBUG for detailed logs
Check connection logs for specific error messages
Review SSL configuration messages
SSE Connection Issues:
Verify SSE endpoint is accessible via /sse
Check for proper content-type headers
Use browser developer tools to inspect SSE connections

Claude Integration

Claude Desktop Configuration

You can integrate Splunk MCP with Claude Desktop by configuring it to use either SSE or STDIO mode. Add the following configuration to your claude_desktop_config.json:

STDIO Mode (Recommended for Desktop)

{
  "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 Mode

{
  "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"]
  }
}

Usage with Claude

Once configured, you can use natural language to interact with Splunk through Claude. Examples:

List available indexes:
```
What Splunk indexes are available?
```

Search Splunk data:

Search Splunk for failed login attempts in the last 24 hours

Get system health:
```
Check the health of the Splunk system
```
Manage KV stores:
```
List all KV store collections
```

The MCP tools will be automatically available to Claude, allowing it to execute these operations through natural language commands.

License

[Your License Here]

Acknowledgments

FastMCP framework
Splunk SDK for Python
Python-decouple for configuration management
SSE Starlette for SSE implementation