Log MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to intelligently inspect and analyze runtime log files for debugging and troubleshooting.

What is this?

This MCP server bridges the gap between your application logs and AI assistants like Claude. When you encounter errors or unexpected behavior in your code, the AI can automatically inspect your runtime logs to diagnose the problem - no more copying and pasting log files back and forth!

The workflow:

1. Your applications write logs to a configured directory (e.g., $XDG_RUNTIME_DIR/log or custom paths)
2. This MCP server gives your AI assistant read access to those logs
3. When you report a problem, the AI proactively checks the logs to find the root cause
4. Get faster, more accurate debugging assistance based on actual runtime data

Use Cases

• Development debugging: AI analyzes application logs when tests fail or errors occur
• Service monitoring: Quickly diagnose issues with background services and daemons
• Multi-project debugging: Monitor logs from multiple applications simultaneously
• Learning & training: Understand what your code is doing at runtime by having AI explain the logs

Features

• Multiple Directory Support: Monitor logs from multiple directories simultaneously
• Automatic AI Guidance: When activated, the AI is informed about log inspection capabilities and will proactively check logs when users report errors
• list_log_files: Lists all log files across all configured directories
• get_log_content: Reads and returns the content of a specific log file
• read_log_paginated: Read large files in chunks with line numbers
• search_log_file: Regex search with context lines and pagination
• runtime-logs prompt: Provides context to the AI about when and how to use log inspection

Installation

From source (development)

git clone <repository-url>
cd log-mcp
pip install -e .

From PyPI (when published)

pip install log-inspector-mcp

Usage

With Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

Default directory ($XDG_RUNTIME_DIR/log):

{
  "mcpServers": {
    "log-inspector": {
      "command": "log-mcp"
    }
  }
}

Single custom directory:

{
  "mcpServers": {
    "log-inspector": {
      "command": "log-mcp",
      "args": ["--log-dir", "/var/log"]
    }
  }
}

Multiple directories:

{
  "mcpServers": {
    "log-inspector": {
      "command": "log-mcp",
      "args": [
        "--log-dir", "/var/log",
        "--log-dir", "/tmp/logs",
        "--log-dir", "$XDG_RUNTIME_DIR/log"
      ]
    }
  }
}

Using environment variable (colon-separated):

{
  "mcpServers": {
    "log-inspector": {
      "command": "log-mcp",
      "env": {
        "LOG_MCP_DIR": "/var/log:/tmp/logs:$XDG_RUNTIME_DIR/log"
      }
    }
  }
}

Or using uvx (recommended):

{
  "mcpServers": {
    "log-inspector": {
      "command": "uvx",
      "args": ["log-mcp", "--log-dir", "/var/log"]
    }
  }
}

Standalone

# Use default directory
log-mcp

# Use single custom directory
log-mcp --log-dir /var/log

# Use multiple directories
log-mcp --log-dir /var/log --log-dir /tmp/logs

# Use environment variable (colon-separated)
LOG_MCP_DIR=/var/log:/tmp/logs log-mcp

# See all options
log-mcp --help

Log Directory Priority

The server determines log directories in this order (highest priority first):

1. --log-dir command-line arguments (can be specified multiple times)
2. LOG_MCP_DIR environment variable (colon-separated paths, like PATH)
3. $XDG_RUNTIME_DIR/log (default)

Multiple Directories

When multiple directories are configured:

• list_log_files scans all directories and returns all found files
• Other tools accept either:
  • Just the filename (searches all directories for the file)
  • Full absolute path (must be within one of the allowed directories)

How It Works

When the MCP server connects to Claude, it automatically informs the AI that:

• Runtime logs are available for inspection
• These logs should be checked whenever users report errors or problems
• The logs contain valuable diagnostic information for troubleshooting

The AI will proactively use the log inspection tools when appropriate.

Tools

list_log_files

Lists all log files found in $XDG_RUNTIME_DIR/log.

Parameters: None

Returns: List of full paths to all log files found

When to use: First step when investigating any error or problem

get_log_content

Reads and returns the complete content of a specific log file.

Parameters:

• filename (string, required): Name of the log file to read

Returns: The full content of the specified log file

When to use: For small log files; for large files, use read_log_paginated instead

read_log_paginated

Reads a specific portion of a log file with token-based pagination to respect AI context limits. Tracks file modifications to detect changes during pagination.

Parameters:

• filename (string, required): Name of the log file to read
• start_line (integer, optional): Starting line number (1-based, default: 1)
• max_tokens (integer, optional): Maximum tokens to return (default: 4000, max: 100000). Uses ~4 chars per token estimation.
• expected_size (integer, optional): Expected file size in bytes (from previous call). Warns if file changed.
• expected_mtime (number, optional): Expected modification timestamp (from previous call). Warns if file was modified.
• num_lines (integer, optional): DEPRECATED - Maximum number of lines (max: 1000). If specified, overrides max_tokens for backward compatibility.

Returns: Lines with line numbers, file metadata (size, mtime), and warnings if file changed during pagination

When to use: For large log files where you need to read specific sections without exceeding context limits

Examples:

• Read from start: start_line=1
• Read 10000 tokens from line 500: start_line=500, max_tokens=10000
• Continue with change detection: start_line=1234, expected_size=5678910, expected_mtime=1234567890.123

File Modification Detection:

• Each response includes file_size and file_mtime
• Use these values in the next call as expected_size and expected_mtime
• If the file changed, you'll get a warning: "⚠️ FILE SIZE CHANGED" or "⚠️ FILE MODIFIED"
• This helps detect when log files are actively being written to

Why token-based? Log lines vary drastically in length. Token-based pagination ensures consistent AI context usage regardless of line length.

search_log_file

Searches a log file using regex patterns and returns matching lines with surrounding context.

Parameters:

• filename (string, required): Name of the log file to search
• pattern (string, required): Regex pattern to search for
• context_lines (integer, optional): Lines to show before/after each match (default: 2, max: 10)
• context_before (integer, optional): Lines to show before each match (max: 10). Overrides context_lines for before-context.
• context_after (integer, optional): Lines to show after each match (max: 10). Overrides context_lines for after-context.
• case_sensitive (boolean, optional): Case-sensitive search (default: false)
• max_matches (integer, optional): Maximum matches to return (default: 50, max: 500)
• skip_matches (integer, optional): Number of matches to skip for pagination (default: 0)

Returns: Matching lines with context, marked with >>> for the match line

When to use: Searching for specific errors, patterns, or events in log files

Examples:

• Search for all "ERROR" entries with 3 lines of context: context_lines=3
• Show 5 lines before and 2 after each match: context_before=5, context_after=2
• Show only lines after the match: context_before=0, context_after=5

Prompts

runtime-logs

A prompt that explains to the AI how and when to use log inspection capabilities. This is automatically available when the server connects.

Example Workflow

1. Configure your application to log to $XDG_RUNTIME_DIR/log/myapp.log
2. Add log-mcp to Claude Desktop config
3. Run your application - it writes logs as it runs
4. Ask Claude for help: "My application is crashing when I click the submit button"
5. Claude automatically:
   • Calls list_log_files to see available logs
   • Calls search_log_file to find error messages
   • Analyzes the error context
   • Provides a solution based on the actual error

No more manual log copy-pasting! The AI has direct, intelligent access to your runtime diagnostics.

Configuring Your Applications to Log

For the AI to help debug your applications, they need to write logs to a directory the MCP server monitors. Here are common configuration patterns:

Default Location: $XDG_RUNTIME_DIR/log

On most Linux systems, $XDG_RUNTIME_DIR is /run/user/<UID> (e.g., /run/user/1000). Create the log directory:

mkdir -p $XDG_RUNTIME_DIR/log

Application-Specific Configuration

Node.js / JavaScript

Using Winston:

const winston = require('winston');

const logger = winston.createLogger({
  transports: [
    new winston.transports.File({
      filename: `${process.env.XDG_RUNTIME_DIR}/log/myapp.log`
    })
  ]
});

Using Pino:

const pino = require('pino');
const logger = pino(
  pino.destination(`${process.env.XDG_RUNTIME_DIR}/log/myapp.log`)
);

Python

Using logging module:

import logging
import os

log_dir = os.path.join(os.environ.get('XDG_RUNTIME_DIR', '/tmp'), 'log')
os.makedirs(log_dir, exist_ok=True)

logging.basicConfig(
    filename=os.path.join(log_dir, 'myapp.log'),
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

Java / Spring Boot

application.properties:

logging.file.path=${XDG_RUNTIME_DIR}/log
logging.file.name=${XDG_RUNTIME_DIR}/log/myapp.log

Rust

Using env_logger:

use std::env;
use std::fs::File;

fn setup_logging() {
    let runtime_dir = env::var("XDG_RUNTIME_DIR").unwrap_or("/tmp".to_string());
    let log_file = format!("{}/log/myapp.log", runtime_dir);

    // Configure your logger to write to log_file
}

Go

package main

import (
    "log"
    "os"
    "path/filepath"
)

func main() {
    runtimeDir := os.Getenv("XDG_RUNTIME_DIR")
    if runtimeDir == "" {
        runtimeDir = "/tmp"
    }

    logPath := filepath.Join(runtimeDir, "log", "myapp.log")
    f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        log.Fatal(err)
    }
    log.SetOutput(f)
}

IDE Configuration

VSCode (for tasks/debugging)

Create .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run with logging",
      "type": "shell",
      "command": "node app.js > $XDG_RUNTIME_DIR/log/myapp.log 2>&1"
    }
  ]
}

IntelliJ IDEA / PyCharm

1. Edit Run Configuration
2. Add VM options or Environment Variables:
   • Set log file path to $XDG_RUNTIME_DIR/log/myapp.log
3. Or modify logging configuration file (logback.xml, log4j.properties, etc.)

Multiple Log Directories

You can monitor logs from different locations simultaneously:

# System logs + application logs + test logs
log-mcp --log-dir /var/log \
        --log-dir $XDG_RUNTIME_DIR/log \
        --log-dir $HOME/projects/myapp/logs

Or use the environment variable:

export LOG_MCP_DIR="/var/log:$XDG_RUNTIME_DIR/log:$HOME/projects/myapp/logs"

Requirements

• Python 3.10+
• MCP SDK
• $XDG_RUNTIME_DIR environment variable (or specify custom directories)