Splunk MCP (Model Context Protocol) Tool

Operating Modes

1. SSE Mode (Default)

2. API Mode

3. STDIO Mode

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

Tools Management

• list_tools

Health Check

• health_check

• ping

User Management

• current_user

• list_users

Index Management

• list_indexes

• get_index_info

• indexes_and_sourcetypes

Search

• search_splunk

• list_saved_searches

KV Store

• list_kvstore_collections

• create_kvstore_collection

• delete_kvstore_collection

SSE Endpoints

• /sse: Returns SSE connection information in text/event-stream format

• /sse/messages: The main SSE stream endpoint

• /sse/health: Health check endpoint for SSE mode

Error Handling

• Invalid search commands or malformed requests

• Insufficient permissions

• Resource not found

• Invalid input validation

• Unexpected server errors

• Connection issues with Splunk server

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:

1. Install dependencies using Poetry:

1. Copy the example environment file and configure your settings:

1. Update the .env file with your Splunk credentials:

Option 2: Docker Installation

1. Pull the latest image:

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

2. Run using Docker Compose:

Usage

Local Usage

1. SSE mode (default for MCP clients):

1. STDIO mode:

Docker Usage

1. SSE Mode (Default):

1. API Mode:

1. STDIO Mode:

Testing with Docker

1. Run all tests:

1. Run specific test components:

Docker Development Tips

1. Building Images:

1. Viewing Logs:

1. Debugging:

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

• 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

1. Default (Secure) Mode:

• Full SSL certificate verification

• Hostname verification enabled

• Recommended for production environments

1. Relaxed Mode:

• SSL certificate verification disabled

• Hostname verification disabled

• Useful for testing or self-signed certificates

Testing

Running Tests

End-to-End SSE Testing

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

Test Structure

1. MCP Integration Tests (tests/test_api.py):

2. Direct Function Tests (tests/test_endpoints_pytest.py):

3. End-to-End MCP Client Tests (test_endpoints.py):

4. Configuration Tests (tests/test_config.py):

Testing Tools

• 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

1. SSL Issues:

• If seeing SSL errors, try setting VERIFY_SSL=false

• Check certificate validity and trust chain

• Verify hostname matches certificate

1. Authentication Issues:

• Verify Splunk credentials

• Check user permissions

• Ensure account is not locked

1. Debugging:

• Set FASTMCP_LOG_LEVEL=DEBUG for detailed logs

• Check connection logs for specific error messages

• Review SSL configuration messages

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

STDIO Mode (Recommended for Desktop)

SSE Mode

Usage with Claude

1. List available indexes:

1. Search Splunk data:

1. Get system health:

1. Manage KV stores:

License

Acknowledgments

• FastMCP framework

• Splunk SDK for Python

• Python-decouple for configuration management

• SSE Starlette for SSE implementation

Splunk MCP (Model Context Protocol) Tool

Operating Modes

1. SSE Mode (Default)

2. API Mode

3. STDIO Mode

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

Tools Management

• list_tools

Health Check

• health_check

• ping

User Management

• current_user

• list_users

Index Management

• list_indexes

• get_index_info

• indexes_and_sourcetypes

Search

• search_splunk

• list_saved_searches

KV Store

• list_kvstore_collections

• create_kvstore_collection

• delete_kvstore_collection

SSE Endpoints

• /sse: Returns SSE connection information in text/event-stream format

• /sse/messages: The main SSE stream endpoint

• /sse/health: Health check endpoint for SSE mode

Error Handling

• Invalid search commands or malformed requests

• Insufficient permissions

• Resource not found

• Invalid input validation

• Unexpected server errors

• Connection issues with Splunk server

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:

1. Install dependencies using Poetry:

1. Copy the example environment file and configure your settings:

1. Update the .env file with your Splunk credentials:

Option 2: Docker Installation

1. Pull the latest image:

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

2. Run using Docker Compose:

Usage

Local Usage

1. SSE mode (default for MCP clients):

1. STDIO mode:

Docker Usage

1. SSE Mode (Default):

1. API Mode:

1. STDIO Mode:

Testing with Docker

1. Run all tests:

1. Run specific test components:

Docker Development Tips

1. Building Images:

1. Viewing Logs:

1. Debugging:

1. Environment Variables:

Security Notes

• 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

• 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

1. Default (Secure) Mode:

• Full SSL certificate verification

• Hostname verification enabled

• Recommended for production environments

1. Relaxed Mode:

• SSL certificate verification disabled

• Hostname verification disabled

• Useful for testing or self-signed certificates

Testing

Running Tests

End-to-End SSE Testing

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

Test Structure

1. MCP Integration Tests (tests/test_api.py):

2. Direct Function Tests (tests/test_endpoints_pytest.py):

3. End-to-End MCP Client Tests (test_endpoints.py):

4. Configuration Tests (tests/test_config.py):

Testing Tools

• 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

1. SSL Issues:

• If seeing SSL errors, try setting VERIFY_SSL=false

• Check certificate validity and trust chain

• Verify hostname matches certificate

1. Authentication Issues:

• Verify Splunk credentials

• Check user permissions

• Ensure account is not locked

1. Debugging:

• Set FASTMCP_LOG_LEVEL=DEBUG for detailed logs

• Check connection logs for specific error messages

• Review SSL configuration messages

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

STDIO Mode (Recommended for Desktop)

SSE Mode

Usage with Claude

1. List available indexes:

1. Search Splunk data:

1. Get system health:

1. Manage KV stores:

License

Acknowledgments

• FastMCP framework

• Splunk SDK for Python

• Python-decouple for configuration management

• SSE Starlette for SSE implementation