Splunk MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude and GitHub Copilot to interact with Splunk for log analysis, troubleshooting, and observability tasks.

Quick Start

{
  "servers": {
    "splunk": {
      "command": "npx",
      "args": ["splunk-mcp-server"],
      "env": {
        "SPLUNK_HOST": "https://your-splunk-host:8089",
        "SPLUNK_USERNAME": "your_username",
        "SPLUNK_PASSWORD": "your_password",
        "SPLUNK_VERIFY_SSL": "false"
      }
    }
  }
}

No installation needed – npx downloads and runs the server automatically.

Features

Available Tools (MVP - Priority 1)

• splunk_search - Execute SPL (Search Processing Language) queries
• splunk_list_indexes - List available Splunk indexes with metadata

Architecture

This MCP server provides a thin, generic client to the Splunk REST API. It follows these principles:

1. Generic Approach - No hardcoded queries or team-specific logic
2. Saved Searches in Splunk - Complex queries are maintained in Splunk
3. Agent-Driven - AI agents build queries dynamically using discovery tools

Requirements

• Node.js >= 18.0.0
• Splunk instance with REST API access (tested with Splunk 9.4.6)
• Valid Splunk credentials

Installation

Development Setup

# Clone the repository
git clone <repository-url>
cd mcp-splunk

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env
# Edit .env with your Splunk credentials

# Build the project
npm run build

# Run in development mode
npm run dev

Production Installation

# From npm registry (once published)
npm install -g splunk-mcp-server

# Or run directly with npx
npx splunk-mcp-server

Configuration

Environment Variables

Create a .env file in the project root:

# Splunk Configuration
SPLUNK_HOST=https://your-splunk-host:8089
SPLUNK_USERNAME=your_username
SPLUNK_PASSWORD=your_password

# SSL Configuration (set to 'false' for self-signed certificates)
SPLUNK_VERIFY_SSL=false

# Connection Timeout (milliseconds)
SPLUNK_TIMEOUT=30000

# Optional: Default search settings
SPLUNK_DEFAULT_EARLIEST_TIME=-1h
SPLUNK_DEFAULT_LATEST_TIME=now
SPLUNK_MAX_RESULTS=1000

Usage

With Claude Desktop / Claude Code

Add to your Claude configuration (~/.config/claude/config.json or .vscode/mcp.json):

{
  "mcpServers": {
    "splunk": {
      "command": "npx",
      "args": ["splunk-mcp-server"],
      "env": {
        "SPLUNK_HOST": "https://your-splunk-host:8089",
        "SPLUNK_USERNAME": "your_username",
        "SPLUNK_PASSWORD": "your_password",
        "SPLUNK_VERIFY_SSL": "false"
      }
    }
  }
}

With GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "splunk": {
      "command": "npx",
      "args": ["splunk-mcp-server"],
      "env": {
        "SPLUNK_HOST": "https://your-splunk-host:8089",
        "SPLUNK_VERIFY_SSL": "false"
      }
    }
  }
}

Testing with MCP Inspector

# Test the server interactively
npm run inspector

# Or with environment variables
SPLUNK_HOST=https://your-splunk-host:8089 \
SPLUNK_USERNAME=user \
SPLUNK_PASSWORD=pass \
SPLUNK_VERIFY_SSL=false \
npx @modelcontextprotocol/inspector tsx src/index.ts

Available Tools

splunk_search

Execute SPL queries to search Splunk logs.

Parameters:

• query (required): SPL query string
• earliestTime (optional): Start of time range (e.g., -24h, 2024-01-01T00:00:00)
• latestTime (optional): End of time range (e.g., now, -1h)
• maxResults (optional): Maximum number of results (default: 100)

Examples:

// Find recent errors
{
  "query": "index=main error | head 10"
}

// Count 500 errors by host
{
  "query": "index=web_logs status=500 | stats count by host",
  "earliestTime": "-24h"
}

// Find exceptions with specific fields
{
  "query": "source=/var/log/app.log exception | fields _time, message",
  "maxResults": 50
}

splunk_list_indexes

List all available Splunk indexes.

Parameters:

• filter (optional): Regex pattern to filter index names
• includeInternal (optional): Include internal Splunk indexes (default: false)

Examples:

// List all user indexes
{
  "includeInternal": false
}

// List indexes matching pattern
{
  "filter": "web.*"
}

// List all indexes including internal
{
  "includeInternal": true
}

Development

Project Structure

mcp-splunk/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── config/
│   │   └── index.ts          # Configuration with Zod validation
│   ├── splunk/
│   │   ├── auth.ts           # Session token management
│   │   ├── client.ts         # REST API client
│   │   ├── search.ts         # Search job management
│   │   └── types.ts          # TypeScript types
│   └── tools/
│       ├── search.ts         # Search tools implementation
│       └── index.ts          # Tool registry
├── package.json
├── tsconfig.json
└── README.md

Scripts

# Development
npm run dev          # Run with tsx (hot reload)
npm run watch        # Watch mode with tsc

# Building
npm run build        # Compile TypeScript

# Testing
npm run test         # Run tests with vitest
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

# Linting
npm run lint         # ESLint
npm run format       # Prettier

# Inspection
npm run inspector    # MCP Inspector

Adding New Tools

1. Define the tool in src/tools/<category>.ts:

export const myNewTool = {
  name: 'my_new_tool',
  description: 'Tool description',
  inputSchema: z.object({
    param: z.string(),
  }),
};

export async function handleMyNewTool(args: z.infer<typeof myNewTool.inputSchema>) {
  // Implementation
}

2. Register in src/tools/index.ts:

import { myNewTool, handleMyNewTool } from './<category>.js';

export const tools = [
  // ... existing tools
  {
    name: myNewTool.name,
    description: myNewTool.description,
    inputSchema: { /* JSON Schema */ },
  },
];

export const toolHandlers = {
  // ... existing handlers
  [myNewTool.name]: handleMyNewTool,
};

Troubleshooting

SSL Certificate Errors

If you encounter SSL certificate verification errors:

# Set SPLUNK_VERIFY_SSL to false for self-signed certificates
SPLUNK_VERIFY_SSL=false

Authentication Failures

• Verify your Splunk username and password
• Check that the Splunk REST API is accessible at the configured host
• Ensure your account has sufficient permissions

Connection Timeouts

• Increase SPLUNK_TIMEOUT in your environment variables
• Check network connectivity to Splunk instance
• Verify firewall rules allow access to port 8089

Query Failures

• Validate SPL syntax using Splunk's search interface first
• Check that you have access to the specified indexes
• Reduce the time range or result count for large queries

Roadmap

Priority 2 - Discovery Tools

• splunk_list_sourcetypes - List sourcetypes in an index
• splunk_get_fields - Get available fields
• splunk_sample_events - Get sample events for learning log structure
• splunk_validate_query - Validate SPL syntax

Priority 3 - Saved Searches

• splunk_list_saved_searches - List available saved searches
• splunk_get_saved_search_details - Get saved search details
• splunk_run_saved_search - Execute a saved search

Priority 4 - Advanced Features

• splunk_get_event_context - Get events around a timestamp
• splunk_search_by_identifier - Search by ID across indexes
• splunk_get_stats - Get statistics (count, timechart, top, rare)
• Job management tools (status, cancel)

Publishing

Publish to npm

# 1. Login to npm (once)
npm login

# 2. Build the project
npm run build

# 3. Publish
npm publish

After publishing, users can run the server with just:

npx splunk-mcp-server

Automated Publishing via GitHub Actions

Create .github/workflows/publish.yml to auto-publish on release tags:

name: Publish to npm
on:
  push:
    tags: ['v*']
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

License

MIT – see LICENSE for details.

Support

For issues and questions:

• Check the troubleshooting section above
• Review Splunk REST API documentation
• Contact the development team