mcp-server-splunk 0.1.0__tar.gz

mcp_server_splunk-0.1.0/.env.example

@@ -0,0 +1,19 @@
+# Splunk Connection Configuration
+
+# Splunk server hostname or IP
+SPLUNK_HOST=localhost
+
+# Splunk management port (default: 8089)
+SPLUNK_PORT=8089
+
+# Connection scheme (http or https)
+SPLUNK_SCHEME=https
+
+# Authentication Method 1: Token-based (recommended)
+# SPLUNK_TOKEN=your-splunk-token-here
+
+# Authentication Method 2: Username/Password (if not using token)
+# SPLUNK_USERNAME=your-username
+# SPLUNK_PASSWORD=your-password
+
+# Note: If SPLUNK_TOKEN is set, it will be used. Otherwise, username/password will be used.

mcp_server_splunk-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MCP
+.mcp/
+.mcp.json
+
+# Claude Code
+.claude/
+
+# Test output
+test_*.json
+test_*.csv

mcp_server_splunk-0.1.0/CLAUDE.md

@@ -0,0 +1,129 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Model Context Protocol (MCP) server that provides 50+ tools for interacting with Splunk. It enables LLM applications like Claude to search, retrieve, and manage data in Splunk instances through a comprehensive REST API wrapper.
+
+## Development Commands
+
+### Setup and Installation
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+# or with uv (recommended)
+uv pip install -r requirements.txt
+```
+
+### Running the MCP Server
+
+```bash
+# Development mode with MCP Inspector
+uv run mcp dev splunk_mcp_server.py
+
+# Direct execution
+python splunk_mcp_server.py
+
+# Install in Claude Desktop
+uv run mcp install splunk_mcp_server.py
+```
+
+### Configuration
+
+The server requires environment variables for Splunk connection. Copy `.env.example` to `.env` and configure:
+- `SPLUNK_HOST`: Splunk server hostname (default: localhost)
+- `SPLUNK_PORT`: Management port (default: 8089)
+- `SPLUNK_SCHEME`: Connection scheme (http/https, default: https)
+- `SPLUNK_TOKEN`: Authentication token (preferred)
+- `SPLUNK_USERNAME` and `SPLUNK_PASSWORD`: Username/password authentication (fallback)
+
+## Architecture
+
+### Core Components
+
+**Connection Management** (`get_splunk_service()` at line 39)
+- Singleton pattern for Splunk service connections
+- Supports both token-based and username/password authentication
+- Token authentication takes precedence if both are configured
+- Uses `splunklib.client` from the Splunk Python SDK
+
+**MCP Server Framework**
+- Built on FastMCP (`mcp.server.fastmcp`)
+- All tools use the `@mcp.tool()` decorator
+- Tools return dictionaries with `success`, `error`, and result data fields
+- Consistent error handling pattern across all tools
+
+### Tool Categories
+
+The 50+ tools are organized into these functional groups:
+
+1. **Search & Query** (lines 73-287): Execute SPL queries, run saved searches, retrieve results
+2. **Index Management** (lines 150-183, 499-543): List indexes, get index details, retrieve statistics
+3. **Alert Management** (lines 682-923): CRUD operations for alerts, view alert history
+4. **Dashboard Operations** (lines 930-1079): Create/read/delete dashboards, manage XML content
+5. **Knowledge Objects** (lines 1086-1280): Lookups, field extractions, data models
+6. **Data Input Management** (lines 1287-1452): Monitor file inputs, network inputs, scripts
+7. **User & Access Management** (lines 1459-1614): Users, roles, capabilities, permissions
+8. **KV Store Operations** (lines 1621-1851): NoSQL-style storage with CRUD operations
+9. **Data Model Tools** (lines 1858-2057): Accelerated data model searches using tstats
+10. **Job Management** (lines 2064-2176): Monitor and control search jobs
+11. **Search Macros** (lines 2183-2427): Reusable search components
+12. **Server Administration** (lines 2434-2783): Server messages, settings, restart checks
+
+### Key Design Patterns
+
+**Namespace Management**
+- Many operations set `service.namespace['app']` to control app context
+- Default app is typically "search" but can be specified per operation
+- Owner defaults to "-" (all users) or "nobody" (global scope)
+
+**Job Lifecycle**
+- Search operations create jobs via `service.jobs.create()`
+- Jobs are polled with `while not job.is_done(): pass`
+- Results are retrieved with `job.results(count=max_count)`
+- Jobs are cancelled with `job.cancel()` to free resources
+
+**Error Handling**
+- All tools return `{"success": bool, ...}` dictionaries
+- KeyError exceptions indicate resource not found
+- Generic exceptions are caught and returned in `error` field
+- No exceptions propagate to the MCP layer
+
+**Data Serialization**
+- REST API responses are parsed from JSON when needed
+- Some endpoints return JSON-encoded strings that require double parsing
+- CSV data for lookups is manually constructed from dictionaries
+- Dashboard XML is passed directly without CDATA wrappers
+
+## Special Considerations
+
+### Query Auto-Prefixing
+The `search_splunk()` tool automatically prefixes queries with `search` if they don't start with recognized commands (`search`, `|`, `from`, `tstats`, `inputlookup`). This is at line 95.
+
+### Dashboard XML Format
+When creating dashboards via `create_dashboard()`, pass plain XML without CDATA wrappers. The XML must include a `<label>` tag. The tool uses `eai:data` parameter for the XML content (line 1037).
+
+### KV Store Operations
+KV Store collections use MongoDB-style query syntax. The SDK provides a `.data` property on collections for CRUD operations:
+- `collection.data.query(**params)` for queries
+- `collection.data.insert(data)` for inserts
+- `collection.data.update(key, data)` for updates
+- Direct REST API call for deletes (line 1832)
+
+### Lookup Table Updates
+The `update_lookup_data()` tool replaces ALL existing data in the lookup table. It converts the list of dictionaries to CSV format manually (lines 1204-1212) before posting to the REST API.
+
+### Large Response Mitigation
+Some tools like `get_data_model()` accept a `summary_only` parameter (default: True) to avoid returning massive JSON payloads. Always use summary mode unless full details are explicitly needed.
+
+## Dependencies
+
+- **mcp[cli]**: FastMCP framework for building MCP servers
+- **splunk-sdk**: Official Splunk Python SDK for REST API interaction
+- **python-dotenv**: Environment variable management from .env files
+
+## Python Version
+
+Requires Python 3.10+ as specified in pyproject.toml.

mcp_server_splunk-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mcp_server_splunk-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: mcp-server-splunk
+Version: 0.1.0
+Summary: A Model Context Protocol server for Splunk - search, manage, and analyze Splunk data via LLMs
+Project-URL: Homepage, https://github.com/pahar0/mcp-server-splunk
+Project-URL: Repository, https://github.com/pahar0/mcp-server-splunk
+Project-URL: Issues, https://github.com/pahar0/mcp-server-splunk/issues
+Author-email: pahar0 <pahar0@users.noreply.github.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai,llm,mcp,model-context-protocol,splunk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: splunk-sdk>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Splunk MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server for Splunk. Enables AI assistants like Claude to search, manage, and analyze data in Splunk instances.
+
+## Installation
+
+### Claude Desktop
+
+Add to your Claude Desktop config:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "splunk": {
+      "command": "uvx",
+      "args": ["mcp-server-splunk"],
+      "env": {
+        "SPLUNK_HOST": "your-splunk-host",
+        "SPLUNK_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add splunk -- uvx mcp-server-splunk \
+  -e SPLUNK_HOST=your-splunk-host \
+  -e SPLUNK_TOKEN=your-token
+```
+
+### OpenAI Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.splunk]
+command = "uvx"
+args = ["mcp-server-splunk"]
+
+[mcp_servers.splunk.env]
+SPLUNK_HOST = "your-splunk-host"
+SPLUNK_TOKEN = "your-token"
+```
+
+### OpenCode
+
+Add to your OpenCode config:
+
+```yaml
+mcp:
+  splunk:
+    type: local
+    command: uvx mcp-server-splunk
+    env:
+      SPLUNK_HOST: your-splunk-host
+      SPLUNK_TOKEN: your-token
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SPLUNK_HOST` | Yes | localhost | Splunk server hostname |
+| `SPLUNK_PORT` | No | 8089 | Splunk management port |
+| `SPLUNK_SCHEME` | No | https | Connection scheme (http/https) |
+| `SPLUNK_TOKEN` | * | - | Authentication token (recommended) |
+| `SPLUNK_USERNAME` | * | - | Username (if not using token) |
+| `SPLUNK_PASSWORD` | * | - | Password (if not using token) |
+
+*Provide either `SPLUNK_TOKEN` or both `SPLUNK_USERNAME` and `SPLUNK_PASSWORD`.
+
+### Getting a Splunk Token
+
+1. Log into Splunk Web
+2. Go to **Settings > Tokens**
+3. Click **New Token**
+4. Copy the token value
+
+## Tools
+
+### Search & Query
+- `search_splunk` - Execute SPL queries
+- `search_async` - Non-blocking searches
+- `search_realtime` - Real-time streaming
+- `export_search_results` - Export to file
+- `run_saved_search` - Execute saved searches
+
+### Index Management
+- `list_indexes` / `get_index_info`
+- `create_index` / `update_index` / `delete_index`
+- `send_event` - Ingest events
+
+### Alerts
+- `list_alerts` / `create_alert` / `update_alert` / `delete_alert`
+- `get_alert_history`
+
+### Saved Searches
+- `list_saved_searches` / `create_saved_search` / `update_saved_search` / `delete_saved_search`
+
+### Dashboards
+- `list_dashboards` / `get_dashboard` / `create_dashboard` / `delete_dashboard`
+
+### Knowledge Objects
+- `list_lookups` / `get_lookup_data` / `update_lookup_data`
+- `list_macros` / `create_macro` / `update_macro` / `delete_macro`
+- `list_field_extractions`
+
+### KV Store
+- `list_kvstore_collections` / `create_kvstore_collection` / `delete_kvstore_collection`
+- `query_kvstore_collection` / `insert_kvstore_data` / `update_kvstore_data` / `delete_kvstore_data`
+
+### Data Inputs
+- `list_inputs` / `get_input_info`
+- `create_monitor_input` / `delete_input`
+
+### Users & Roles
+- `list_users` / `get_user_info` / `create_user` / `update_user` / `delete_user`
+- `list_roles` / `get_role_info` / `create_role` / `update_role` / `delete_role`
+
+### Apps
+- `list_apps` / `create_app` / `update_app` / `delete_app`
+
+### Server
+- `get_server_info` / `get_server_settings`
+- `check_restart_required` / `restart_splunk` / `refresh_splunk`
+- `list_jobs` / `get_job_results` / `cancel_job`
+
+## Example Prompts
+
+- "Search for errors in the last hour"
+- "List all indexes and their sizes"
+- "Create an alert for failed logins"
+- "Show dashboards in the security app"
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/pahar0/mcp-server-splunk.git
+cd mcp-server-splunk
+uv sync
+
+# Run locally
+export SPLUNK_HOST=localhost SPLUNK_TOKEN=your-token
+uv run mcp-server-splunk
+
+# Debug with MCP Inspector
+npx @modelcontextprotocol/inspector uv run mcp-server-splunk
+```
+
+## License
+
+Apache 2.0

mcp_server_splunk-0.1.0/README.md

@@ -0,0 +1,159 @@
+# Splunk MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server for Splunk. Enables AI assistants like Claude to search, manage, and analyze data in Splunk instances.
+
+## Installation
+
+### Claude Desktop
+
+Add to your Claude Desktop config:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "splunk": {
+      "command": "uvx",
+      "args": ["mcp-server-splunk"],
+      "env": {
+        "SPLUNK_HOST": "your-splunk-host",
+        "SPLUNK_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add splunk -- uvx mcp-server-splunk \
+  -e SPLUNK_HOST=your-splunk-host \
+  -e SPLUNK_TOKEN=your-token
+```
+
+### OpenAI Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.splunk]
+command = "uvx"
+args = ["mcp-server-splunk"]
+
+[mcp_servers.splunk.env]
+SPLUNK_HOST = "your-splunk-host"
+SPLUNK_TOKEN = "your-token"
+```
+
+### OpenCode
+
+Add to your OpenCode config:
+
+```yaml
+mcp:
+  splunk:
+    type: local
+    command: uvx mcp-server-splunk
+    env:
+      SPLUNK_HOST: your-splunk-host
+      SPLUNK_TOKEN: your-token
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SPLUNK_HOST` | Yes | localhost | Splunk server hostname |
+| `SPLUNK_PORT` | No | 8089 | Splunk management port |
+| `SPLUNK_SCHEME` | No | https | Connection scheme (http/https) |
+| `SPLUNK_TOKEN` | * | - | Authentication token (recommended) |
+| `SPLUNK_USERNAME` | * | - | Username (if not using token) |
+| `SPLUNK_PASSWORD` | * | - | Password (if not using token) |
+
+*Provide either `SPLUNK_TOKEN` or both `SPLUNK_USERNAME` and `SPLUNK_PASSWORD`.
+
+### Getting a Splunk Token
+
+1. Log into Splunk Web
+2. Go to **Settings > Tokens**
+3. Click **New Token**
+4. Copy the token value
+
+## Tools
+
+### Search & Query
+- `search_splunk` - Execute SPL queries
+- `search_async` - Non-blocking searches
+- `search_realtime` - Real-time streaming
+- `export_search_results` - Export to file
+- `run_saved_search` - Execute saved searches
+
+### Index Management
+- `list_indexes` / `get_index_info`
+- `create_index` / `update_index` / `delete_index`
+- `send_event` - Ingest events
+
+### Alerts
+- `list_alerts` / `create_alert` / `update_alert` / `delete_alert`
+- `get_alert_history`
+
+### Saved Searches
+- `list_saved_searches` / `create_saved_search` / `update_saved_search` / `delete_saved_search`
+
+### Dashboards
+- `list_dashboards` / `get_dashboard` / `create_dashboard` / `delete_dashboard`
+
+### Knowledge Objects
+- `list_lookups` / `get_lookup_data` / `update_lookup_data`
+- `list_macros` / `create_macro` / `update_macro` / `delete_macro`
+- `list_field_extractions`
+
+### KV Store
+- `list_kvstore_collections` / `create_kvstore_collection` / `delete_kvstore_collection`
+- `query_kvstore_collection` / `insert_kvstore_data` / `update_kvstore_data` / `delete_kvstore_data`
+
+### Data Inputs
+- `list_inputs` / `get_input_info`
+- `create_monitor_input` / `delete_input`
+
+### Users & Roles
+- `list_users` / `get_user_info` / `create_user` / `update_user` / `delete_user`
+- `list_roles` / `get_role_info` / `create_role` / `update_role` / `delete_role`
+
+### Apps
+- `list_apps` / `create_app` / `update_app` / `delete_app`
+
+### Server
+- `get_server_info` / `get_server_settings`
+- `check_restart_required` / `restart_splunk` / `refresh_splunk`
+- `list_jobs` / `get_job_results` / `cancel_job`
+
+## Example Prompts
+
+- "Search for errors in the last hour"
+- "List all indexes and their sizes"
+- "Create an alert for failed logins"
+- "Show dashboards in the security app"
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/pahar0/mcp-server-splunk.git
+cd mcp-server-splunk
+uv sync
+
+# Run locally
+export SPLUNK_HOST=localhost SPLUNK_TOKEN=your-token
+uv run mcp-server-splunk
+
+# Debug with MCP Inspector
+npx @modelcontextprotocol/inspector uv run mcp-server-splunk
+```
+
+## License
+
+Apache 2.0

mcp_server_splunk-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mcp-server-splunk"
+version = "0.1.0"
+description = "A Model Context Protocol server for Splunk - search, manage, and analyze Splunk data via LLMs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+authors = [
+    {name = "pahar0", email = "pahar0@users.noreply.github.com"}
+]
+keywords = ["mcp", "splunk", "llm", "ai", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "splunk-sdk>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+mcp-server-splunk = "splunk_mcp_server:main"
+
+[project.urls]
+Homepage = "https://github.com/pahar0/mcp-server-splunk"
+Repository = "https://github.com/pahar0/mcp-server-splunk"
+Issues = "https://github.com/pahar0/mcp-server-splunk/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

mcp_server_splunk-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+mcp>=1.0.0
+splunk-sdk>=2.0.0