MCP Linux Log Server

A distributed MCP (Model Context Protocol) server that exposes Linux system logs to AI for diagnostic and predictive analysis.

Overview

MCP Log Server allows Claude and other AI assistants to read and analyze your system logs, including:

• systemd journal (journalctl) - Structured system logs

• Traditional syslog - /var/log/syslog, auth.log, etc. (Phase 3)

• Kernel logs - dmesg output (Phase 3)

• Application logs - nginx, apache, postgresql, etc. (Phase 3)

Architecture: One MCP server per machine (distributed model)

• Local PC: stdio transport → Claude Desktop

• Remote machines: HTTP/SSE transport over network

• Each server reads only its local logs (no SSH complexity)

Related MCP server: systemd-mcp

Current Status: Phase 3 Complete

✅ Implemented:

• Systemd journal reading with rich filtering

  • Time filtering (relative and absolute)

  • Priority/severity filtering

  • Unit-specific filtering

  • Boot filtering

• Syslog files (auth.log, syslog, kern.log)

  • Secure file reading with path validation

  • Text search and line limits

  • Tail mode for recent entries

• Kernel logs (dmesg)

  • Time and priority filtering

  • Direct kernel ring buffer access

• Application logs (nginx, apache, postgresql)

  • Auto-detection based on file existence

  • Support for log rotation patterns (globs)

  • Error and access logs

• Configuration management (YAML)

• Transport modes: stdio (Claude Desktop) and HTTP/SSE (remote)

⏳ Planned (Phases 4-5):

• Enhanced deployment automation

• Systemd service files for remote servers

• TLS/HTTPS support

• Real-time log streaming

• Log aggregation across machines

Features

Resource URIs

Access logs via hierarchical URIs with query parameters:

Systemd Journal:

log://systemd/journal?since=now-24h&priority=err&limit=500
log://systemd/errors
log://systemd/current-boot
log://systemd/journal/nginx.service

Syslog Files:

log://syslog/syslog?tail=true&limit=1000
log://syslog/auth?grep=failed
log://syslog/kern

Kernel Logs (dmesg):

log://kernel/dmesg?since=1 hour ago
log://kernel/errors

Application Logs:

log://app/nginx/error?tail=true&limit=500
log://app/nginx/access?grep=404
log://app/apache2/error
log://app/postgresql/main

Docker Container Logs:

log://docker/containers                          # List all containers
log://docker/containers?all=true                 # Include stopped containers
log://docker/myapp?tail=200&since=now-1h
log://docker/postgres-db?grep=error

Query Parameters

• since / until - Time filters (ISO 8601 or relative like "now-24h", "2d")

• priority - Log level (emerg, alert, crit, err, warning, notice, info, debug)

• limit - Max entries (default: 1000, max: 10000)

• grep - Text search filter

• unit - Filter by systemd unit

• boot - Boot ID or relative (0=current, -1=previous)

Deployment

The server runs in two deployment modes:

• Direct (native) install — best for stdio clients on the same machine (Claude Desktop, Claude Code, LM Studio).

• Docker — best for long-running HTTP deployments and remote AI clients.

A full step-by-step guide for both modes, plus client-specific setup for Claude Desktop, Claude Code, OpenCode, LM Studio, Open WebUI, Continue, Cline, Cursor, and Zed, is in RUNNING.md. The condensed quick-start lives below.

Prerequisites (direct install)

• Linux system with systemd

• Python 3.10 or higher

• uv - Modern Python package manager

• System dependencies:

  • libsystemd-dev - Required for systemd-python bindings

Install system dependencies on Debian/Ubuntu:

sudo apt install libsystemd-dev

Install uv if not already installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

Quick Install (direct)

1. Clone or download this repository:

   cd /path/to/mcp-log-server

2. Run the installation script:

   ./scripts/install.sh

3. Important: Log out and log back in for group membership to take effect

4. Test the installation:

   python3 scripts/test-access.py

Quick Install (Docker)

cd /path/to/mcp-log-server
docker compose up -d
docker compose logs -f

The HTTP endpoint is published on host port 3001 by default, mapped to container port 8000. Connect MCP clients at http://<host-ip>:3001/mcp. For volume mounts, build details, and capability tuning see DOCKER.md.

Manual Installation

If you prefer manual installation:

1. Install system dependencies:

   sudo apt install libsystemd-dev

2. Create virtual environment and install:

   uv venv
   uv pip install -e .

3. Add your user to the systemd-journal group:

   sudo usermod -aG systemd-journal $USER

4. Log out and log back in

5. Create config directory:

   mkdir -p ~/.config/mcp-log-server

Configuration

Connecting an AI client

See RUNNING.md for full, copy-pasteable configs for:

• Claude Desktop

• Claude Code (claude mcp add ...)

• OpenCode

• LM Studio

• Open WebUI (via mcpo bridge)

• Continue, Cline, Cursor, Zed

• Generic MCP clients (stdio + Streamable HTTP at /mcp)

Minimum example — Claude Desktop pointing at a local install:

{
  "mcpServers": {
    "local-logs": {
      "command": "/path/to/mcp-log-server/.venv/bin/mcp-log-server"
    }
  }
}

Restart the client after editing its config.

Remote / HTTP access

Run the server with --http (native) or via docker compose up -d (Docker). Clients then connect at http://<host>:<port>/mcp — for example:

{
  "mcpServers": {
    "remote-logs": {
      "url": "http://192.0.2.100:3001/mcp",
      "transport": "http"
    }
  }
}

Use the /mcp path, not /sse. The legacy SSE transport is not served in --http mode — see RUNNING.md for the workaround if a client only speaks SSE.

Custom Configuration

Create ~/.config/mcp-log-server/local.yaml to override defaults:

server:
  machine_name: my-server
  max_entries: 2000

sources:
  systemd:
    enabled: true

security:
  max_file_size: 209715200  # 200MB

See config/default.yaml for all available options.

Usage with Claude Desktop

Once installed and configured with Claude Desktop, you can ask Claude questions like:

• "Show me systemd errors from the last 24 hours"

• "What's happening with nginx?"

• "Show me kernel boot messages"

• "Are there any failed systemd units?"

• "Check authentication logs for failed login attempts"

• "Show me recent nginx errors"

• "What kernel errors occurred in the last hour?"

• "Check postgres logs for issues"

• "Show me failed SSH login attempts"

Claude will:

1. See available log resources via MCP

2. Determine appropriate resource URI and filters

3. Read and analyze the logs

4. Provide insights and recommendations

Usage with Ollama (Local Models)

For fully-local, offline log analysis the project ships scripts that call the readers directly and pipe results through Ollama — no MCP client required. See RUNNING.md — Part 3 for model recommendations, the analysis scripts, and cron-based monitoring.

Quick start with Ollama:

uv pip install -e ".[ollama]"
ollama pull qwen2.5:14b
uv run python scripts/analyze-logs.py

Command Line Usage

You can also run the server directly:

# stdio mode (for Claude Desktop)
uv run mcp-log-server

# HTTP/SSE mode (for remote access)
uv run mcp-log-server --http --port 8000

# Custom config file
uv run mcp-log-server --config /path/to/config.yaml

# Or using python -m
uv run python -m mcp_log_server.server

Security

• Read-Only: Server never modifies logs or system

• No Root Required: Uses systemd-journal group for journal access

• Path Validation: File-based logs restricted to allowed paths

• Resource Limits: Max entries, file sizes, and response sizes enforced

• Container Security: Docker deployment uses minimal capabilities (SYSLOG vs SYS_ADMIN)

• Network Security: Designed for reverse proxy deployment with HTTPS and authentication

Troubleshooting

Permission Denied Errors

If you get permission errors when reading the journal:

1. Check group membership:

   groups

   You should see systemd-journal in the list.

2. If not, run:

   sudo usermod -aG systemd-journal $USER

3. Important: Log out and log back in (or reboot)

4. Verify again:

   groups
   journalctl -n 10  # Should work without sudo

Claude Desktop Not Seeing Server

1. Check the config file path is correct:

   • Use absolute paths, not ~

   • Use /home/$(whoami)/.local/bin/mcp-log-server

2. Verify the command exists:

   which mcp-log-server
   ls -l ~/.local/bin/mcp-log-server

3. Test manually:

   mcp-log-server

   Should start without errors.

4. Check Claude Desktop logs for errors

No Entries Returned

1. Test journal access:

   journalctl -n 10

2. Run pre-flight checks:

   python3 scripts/test-access.py

3. Check time filters - relative times like "now-24h" may not match if your journal is older

Development

Project Structure

mcp-log-server/
├── src/mcp_log_server/
│   ├── server.py              # Main FastMCP server
│   ├── config.py              # Configuration management
│   ├── resources/
│   │   └── systemd.py         # systemd journal resources
│   ├── readers/
│   │   └── journal_reader.py  # Journal reading logic
│   ├── filters/               # Query filters (future)
│   └── utils/                 # Utilities (future)
├── config/
│   ├── default.yaml           # Default configuration
│   └── claude-desktop.json.example
├── scripts/
│   ├── install.sh             # Installation script
│   ├── setup-permissions.sh   # Permission setup
│   └── test-access.py         # Pre-flight checks
└── pyproject.toml

Running Tests

pip install -e ".[dev]"
pytest

Roadmap

Phase 2: Enhanced Filtering ✅ (Integrated into Phase 3)

• Advanced time parsing ✅

• Complex query combinations ✅

• Extended resource types ✅

Phase 3: Additional Log Sources ✅ Complete

• Traditional syslog files ✅

• Kernel logs (dmesg) ✅

• Application-specific logs (nginx, apache, postgresql) ✅

• Auto-detection of installed applications ✅

Phase 4: Remote Access (Partially Complete)

• Systemd service file for auto-start

• TLS/HTTPS support

• Authentication (API keys, basic auth)

Phase 5: Advanced Features

• Real-time log streaming

• Log aggregation across machines

• Custom log parsers

• Statistics and summaries

• Alerting integration

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

Support

• Issues: https://github.com/GrumpyMetalGuy/mcp-log-server/issues

• Documentation: See this README and code comments

Acknowledgments

• Built with FastMCP - Python MCP SDK

• Uses systemd-python for journal access