Splunk MCP Server

This project is a Model Context Protocol (MCP) server written in Go. It exposes a splunk_search tool, allowing Large Language Models (LLMs) and other MCP-compliant clients (like LM Studio) to execute searches against a Splunk instance.

Features

• Exposes a single splunk_search tool to any MCP-compliant client.
• Supports simple SPL queries as a direct string argument.
• Supports advanced searches with time ranges and result limits via a JSON string argument.
• Flexible configuration via a configuration file or environment variables.

Getting Started

To get started with this project, clone the repository and its submodules:

git clone --recurse-submodules https://github.com/magifd2/splunk-mcp-go.git
cd splunk-mcp-go

If you have already cloned the repository without the submodules, you can initialize them with:

git submodule update --init --recursive

Prerequisites

• Go (version 1.21 or later)
• Access to a Splunk instance.
• An authentication token for the Splunk instance.

Configuration

The server can be configured in multiple ways. The order of precedence is: command-line flags > environment variables > configuration file.

1. Command-line Flags (Highest Priority)

• --config <path>: Path to a custom configuration file.
• --debug: Enable verbose debug logging.

2. Environment Variables

Set the following environment variables before running the server:

export SPLUNK_HOST="https://your-splunk-host:8089"
export SPLUNK_TOKEN="your-splunk-token"

3. Configuration File

The server looks for config.json in ~/.config/splunk-mcp-server/ by default. This can be overridden by the --config flag.

Example config.json:

{
  "host": "https://your-splunk-host:8089",
  "token": "your-splunk-token",
  "insecure": true
}

Building

To build the server for all platforms and create release packages, use the Makefile:

# Build binaries for macOS, Linux, and Windows
make build

# Create zipped archives for release
make package

Usage

The server communicates over standard input/output (stdio). To use it with an MCP client, you need to configure the client to execute the server command.

LM Studio Configuration (Recommended)

In LM Studio, you can configure the server by editing the mcp.json file. This is the recommended method as you can set the required environment variables directly in the configuration.

Example mcp.json entry:

{
  "mcpServers": {
    "splunk-mcp": {
      "command": "/path/to/your/splunk-mcp-server",
      "env": {
        "SPLUNK_HOST": "https://your-splunk-host:8089",
        "SPLUNK_TOKEN": "your-splunk-token"
      }
    }
  }
}

Replace /path/to/your/splunk-mcp-server with the actual full path to the built binary.

General Usage (Other Clients)

If your client does not support setting environment variables directly, you can use a wrapper script.

1. Create start.sh: Copy the template file cp start.sh.template start.sh.
2. Edit start.sh: Open your new start.sh file and fill in your SPLUNK_HOST and SPLUNK_TOKEN.
3. Make it executable: chmod +x start.sh
4. Configure your MCP Client: In your client's settings, specify the full path to the start.sh script as the command to execute.

Tool: splunk_search

The server exposes a single tool named splunk_search.

Description

Executes a Splunk search query. The 'query' parameter can be a simple string or a JSON string object with keys like 'query', 'limit', 'earliest_time'.

Arguments

The tool takes a single string argument. The server intelligently parses this string.

Simple Usage

Pass the SPL query directly as a string.

Example:

"index=_internal | head 5"

Advanced Usage

To specify parameters like time ranges or result limits, pass a JSON string as the argument.

Example:

"{\"query\": \"index=main\", \"earliest_time\": \"-24h\", \"limit\": 50}"

Available JSON keys:

• query (string, required): The SPL query.
• earliest_time (string, optional): The earliest time for the search (e.g., "-1h", "@d").
• latest_time (string, optional): The latest time for the search (e.g., "now").
• limit (int, optional): The maximum number of results to return.