LogScribe

A Model Context Protocol (MCP) server for log file management and analysis with enhanced formatting and error handling.

✨ Features

• 📁 List Log Files - View all .log files with size and modification metadata
• 📖 Read Log Files - Read the last N lines with line numbers and formatting
• 🔍 Search Individual Files - Search for patterns within specific log files
• 🌐 Cross-File Search - Search patterns across all log files simultaneously
• 🏷️ Filter by Log Level - Filter entries by ERROR, WARN, INFO, DEBUG, CRITICAL
• 📊 Generate Analytics - Comprehensive log file summaries and statistics
• ✅ Error Handling - Graceful handling of missing files and edge cases
• 🎨 Rich Output - Formatted output with emojis and visual separators
• 🔧 Hot Reload - Auto-restart on file changes during development

Quick Start

1. Install dependencies:

   pip install -r requirements.txt
   

2. Create logs directory (optional):

   mkdir logs
   # Add some .log files to test
   echo "2024-01-01 INFO Application started" > logs/app.log
   

   (You could also use sample logs in the logs folder to get started.)

3. Run the server:

   # Use default ./logs directory
   python mcp_server.py
   
   # Use custom logs directory (command line)
   python mcp_server.py /path/to/your/logs
   
   # Use custom logs directory (environment variable)
   LOGS_DIR="/path/to/your/logs" python mcp_server.py
   
   # Development (with hot reload)
   python dev_server.py
   

Available Tools

list_files()

Lists all .log files in the ./logs directory with file size information.

Example output:

📁 Log Files:
app.log (2.5 KB)
error.log (1.2 KB)

read_file(filename: str, lines: int = 10)

Reads the last N lines from a specified log file with enhanced formatting.

Parameters:

• filename: Name of the log file (e.g., "app.log")
• lines: Number of lines to read from the end (default: 10)

Example output:

📄 app.log (showing last 3 of 100 lines)
──────────────────────────────────────────────────
  98 | 2024-01-01 10:00:00 INFO Application started
  99 | 2024-01-01 10:01:00 DEBUG Loading configuration
 100 | 2024-01-01 10:02:00 INFO Ready to serve requests

search_logs(filename: str, pattern: str, lines: int = 20)

Searches for a pattern within a specific log file using case-insensitive regex.

Parameters:

• filename: Name of the log file to search
• pattern: Search pattern (supports regex)
• lines: Maximum number of matching lines to return (default: 20)

search_all_logs(pattern: str, max_results: int = 50)

Searches for a pattern across ALL log files simultaneously.

Parameters:

• pattern: Search pattern (supports regex)
• max_results: Maximum number of matching lines to return (default: 50)

log_summary(filename: str)

Generates comprehensive analytics and statistics for a log file.

Parameters:

• filename: Name of the log file to analyze

Claude Desktop Integration

Add to your claude_desktop_config.json:

Option 1: Default logs directory

{
  "mcpServers": {
    "log-server": {
      "command": "/full/path/to/your/venv/bin/python",
      "args": ["/full/path/to/your/mcp_server.py"],
      "cwd": "/full/path/to/your/project"
    }
  }
}

Option 2: Custom logs directory (command line)

{
  "mcpServers": {
    "log-server": {
      "command": "/full/path/to/your/venv/bin/python",
      "args": ["/full/path/to/your/mcp_server.py", "/path/to/your/logs"],
      "cwd": "/full/path/to/your/project"
    }
  }
}

Option 3: Custom logs directory (environment variable)

{
  "mcpServers": {
    "log-server": {
      "command": "/full/path/to/your/venv/bin/python",
      "args": ["/full/path/to/your/mcp_server.py"],
      "cwd": "/full/path/to/your/project",
      "env": {
        "LOGS_DIR": "/path/to/your/logs"
      }
    }
  }
}

Configuration

Logs Directory

The server supports three ways to specify where your log files are located:

1. Default: Uses ./logs directory in the project folder
2. Command Line: Pass directory path as first argument

   python mcp_server.py /var/log/myapp
   

3. Environment Variable: Set LOGS_DIR environment variable

   export LOGS_DIR="/var/log/myapp"
   python mcp_server.py
   

Priority order: Command Line > Environment Variable > Default

Example Usage

Ask Claude:

• "List all my log files"
• "Show me the last 20 lines from app.log"
• "Read the last 5 lines from error.log"
• "Search for 'ERROR' in app.log"
• "Show me all ERROR entries in app.log"
• "Search for 'PaymentService' across all my logs"
• "Generate a summary of app.log"

Error Handling

The server gracefully handles:

• Missing log files (returns helpful error message)
• Empty log files (indicates file is empty)
• Invalid file paths

Requirements

• Python 3.8+
• mcp>=1.9.3
• watchdog>=3.0.0 (for development hot reload)
• pytest>=8.4.0 (for running tests)

Testing

Run the included tests to verify everything works:

# Simple test runner
python tests/test_basic.py

# Or using pytest (install first: pip install pytest)
pytest tests/ -v

Tests cover:

• Server initialization and configuration
• Log directory selection logic (env vars, command line args)
• Basic functionality verification

Development

For development with automatic restart on file changes:

python dev_server.py

The development server will automatically restart when you modify any .py files, making it easier to test changes without manually restarting.