Glama
splunk-mcp

# 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

2. **API Mode**
   - RESTful API endpoints
   - Access via `/api/v1` endpoint prefix
   - Start with `python splunk_mcp.py api`

3. **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

1. Clone the repository:
```bash
git clone <repository-url>
cd splunk-mcp
```

2. Install dependencies using Poetry:
```bash
poetry install
```

3. Copy the example environment file and configure your settings:
```bash
cp .env.example .env
```

4. Update the `.env` file with your Splunk credentials:
```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
```

### Option 2: Docker Installation

1. Pull the latest image:
```bash
docker pull livehybrid/splunk-mcp:latest
```

2. Create your `.env` file as above or use environment variables directly.

3. Run using Docker Compose:
```bash
docker-compose up -d
```

Or using Docker directly:
```bash
docker run -i \
  --env-file .env \
  livehybrid/splunk-mcp
```

## Usage

### Local Usage

The tool can run in three modes:

1. SSE mode (default for MCP clients):
```bash
# 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
```

3. STDIO mode:
```bash
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):
```bash
docker compose up -d mcp
```

2. API Mode:
```bash
docker compose run --rm mcp python splunk_mcp.py api
```

3. STDIO Mode:
```bash
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:
```bash
./run_tests.sh --docker
```

2. Run specific test components:
```bash
# 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**:
```bash
# Build both images
docker compose build

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

2. **Viewing Logs**:
```bash
# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp
```

3. **Debugging**:
```bash
# 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

2. **SSL Verification**:
- `VERIFY_SSL=true` recommended for production
- Can be disabled for development/testing
- Configure through environment variables

3. **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:

1. **Default (Secure) Mode**:
```env
VERIFY_SSL=true
```
- Full SSL certificate verification
- Hostname verification enabled
- Recommended for production environments

2. **Relaxed Mode**:
```env
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:
```bash
poetry run pytest
```

With coverage reporting:
```bash
poetry run pytest --cov=splunk_mcp
```

With verbose output:
```bash
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:

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

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

2. **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

3. **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

4. **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

1. **Basic Connectivity**:
- The tool now performs a basic TCP connectivity test
- Check if port 8089 is accessible
- Verify network routing and firewalls

2. **SSL Issues**:
- If seeing SSL errors, try setting `VERIFY_SSL=false`
- Check certificate validity and trust chain
- Verify hostname matches certificate

3. **Authentication Issues**:
- Verify Splunk credentials
- Check user permissions
- Ensure account is not locked

4. **Debugging**:
- Set `FASTMCP_LOG_LEVEL=DEBUG` for detailed logs
- Check connection logs for specific error messages
- Review SSL configuration messages

5. **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)
```json
{
  "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
```json
{
  "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:

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

2. Search Splunk data:
```
Search Splunk for failed login attempts in the last 24 hours
```

3. Get system health:
```
Check the health of the Splunk system
```

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