loganalysis-mcpserver 0.1.1
A Model Context Protocol (MCP) server for querying and analyzing Splunk logs using natural language
License: MIT
Requires Python: >=3.13
Keywords: ai, llm, log-analysis, logs, mcp, model-context-protocol, observability, splunk

# Log Analysis MCP Server

A Model Context Protocol (MCP) server that connects to Splunk for querying and analyzing logs using natural language.

## Prerequisites

- **Python 3.13+** installed on your system
- **uv** (Python package installer) - [Install from here](https://docs.astral.sh/uv/)
- **Splunk instance** with:
  - API access URL
  - Bearer token for authentication
  - (Optional) SSL certificate if using custom CA

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install loganalysis-mcpserver
```

### Option 2: Install from Source

```bash
git clone <your-repo-url>
cd splunk-mcp
pip install -e .
```

## Configuration

### 1. Environment Variables

Create a `.env` file in the project root:

```env
SPLUNK_HOST=https://your-splunk-instance.com
SPLUNK_BEARER_TOKEN=your-bearer-token-here
SPLUNK_TIMEOUT=300

# Optional: SSL Certificate (base64 encoded or plain PEM format)
SPLUNK_SSL_CERT=-----BEGIN CERTIFICATE-----...
```

**Note:** The server uses Bearer token authentication, not username/password.

### 2. MCP Configuration

Add this to your MCP configuration file:

**For Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "splunk-logs": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "SPLUNK_HOST": "https://your-splunk-instance.com",
        "SPLUNK_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}
```

**For VS Code / Other MCP Clients** (`mcp.json` or similar):

```json
{
  "servers": {
    "splunk-logs": {
      "command": "python",
      "args": ["-m", "src.server"]
    }
  }
}
```

**Note:** Ensure the package is installed in the same Python environment your MCP client uses.

## Running the Server

### Local Development (stdio transport)

```bash
cd src
python server.py
```

### SSE Transport (Server-Sent Events)

Set environment variables:
```env
MCP_TRANSPORT=sse
MCP_HOST=127.0.0.1
MCP_PORT=12212
```

Then run:
```bash
python server.py
```

## Usage

Once connected, you can query Splunk logs using natural language:

**Example queries:**
- "Show me error logs from the last hour"
- "Find all logs with trace ID xyz123"
- "Count logs by source in the last 24 hours"

The MCP server will convert your queries to SPL (Splunk Processing Language) and return detailed analysis.

## Features

- ✅ Natural language to SPL conversion
- ✅ Comprehensive log analysis with multiple detail levels
- ✅ Timeline and performance metrics
- ✅ Error detection and highlighting
- ✅ Support for trace IDs and correlation
- ✅ Automatic query sanitization for security
- ✅ Configurable timeouts and result limits
- ✅ SSL certificate support

## Project Structure

```
loganalysis_mcpserver/
├── src/
│   ├── server.py              # Main MCP server
│   ├── splunk_api.py          # Splunk API integration
├── pyproject.toml             # Dependencies
├── .env                       # Environment variables (create this)
└── README.md                  # This file
```

## Troubleshooting

### "SPLUNK_HOST not configured"
- Check your `.env` file exists in project root
- Verify `SPLUNK_HOST` variable is set correctly

### "Authentication failed"
- Verify your `SPLUNK_BEARER_TOKEN` is valid
- Check token hasn't expired

### SSL Certificate Issues
- Use `SPLUNK_SSL_CERT` environment variable
- Certificate can be base64 encoded or plain PEM format
- Server automatically creates `splunk_ca_bundle.pem`

### No Results
- Check your SPL query syntax
- Verify time range (earliest_time, latest_time)
- Ensure you have access to the Splunk index

## Security

⚠️ **Important:**
- Queries are automatically sanitized to prevent injection attacks
- Dangerous SPL commands (delete, script, sendemail) are blocked

## Dependencies

- `mcp[cli]` - Model Context Protocol framework
- `fastmcp` - FastMCP server implementation  
- `requests` - HTTP client for Splunk API
- `python-dotenv` - Environment variable loader

## Advanced Configuration

### Custom Transport

The server supports two transport modes:

1. **stdio** (default) - For local development and direct communication
2. **sse** - Server-Sent Events for HTTP-based communication

Set via environment variables:
```env
MCP_TRANSPORT=stdio  # or "sse"
MCP_HOST=127.0.0.1
MCP_PORT=12212
```

### Query Parameters

When executing queries, you can customize:

- `earliest_time` - Start time (e.g., "-1h", "-24h", "-30m")
- `latest_time` - End time (e.g., "now")
- `max_count` - Max results (0 = unlimited)
- `timeout` - Request timeout in seconds