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:
- Your applications write logs to a configured directory (e.g.,
$XDG_RUNTIME_DIR/logor custom paths) - This MCP server gives your AI assistant read access to those logs
- When you report a problem, the AI proactively checks the logs to find the root cause
- 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):
--log-dircommand-line arguments (can be specified multiple times)LOG_MCP_DIRenvironment variable (colon-separated paths, likePATH)$XDG_RUNTIME_DIR/log(default)
Multiple Directories
When multiple directories are configured:
list_log_filesscans 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 readstart_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_sizeandfile_mtime - Use these values in the next call as
expected_sizeandexpected_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 searchpattern(string, required): Regex pattern to search forcontext_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). Overridescontext_linesfor before-context.context_after(integer, optional): Lines to show after each match (max: 10). Overridescontext_linesfor 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
- Configure your application to log to
$XDG_RUNTIME_DIR/log/myapp.log - Add log-mcp to Claude Desktop config
- Run your application - it writes logs as it runs
- Ask Claude for help: "My application is crashing when I click the submit button"
- Claude automatically:
- Calls
list_log_filesto see available logs - Calls
search_log_fileto find error messages - Analyzes the error context
- Provides a solution based on the actual error
- Calls
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
- Edit Run Configuration
- Add VM options or Environment Variables:
- Set log file path to
$XDG_RUNTIME_DIR/log/myapp.log
- Set log file path to
- 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_DIRenvironment variable (or specify custom directories)