What is Logscribe Mcp

logscribe-mcp is a lightweight tool designed to manage and analyze local log files using the Model Context Protocol (MCP).

Use cases

Use cases include monitoring application logs, debugging issues, analyzing system performance, and generating reports from log data.

How to use

To use logscribe-mcp, install the required dependencies, create a logs directory (optional), and run the server using Python. You can specify the logs directory via command line or environment variable.

Key features

Key features include listing log files, reading specific lines, searching patterns within and across files, filtering by log level, generating analytics, error handling, rich output formatting, and hot reload functionality.

Where to use

logscribe-mcp can be used in software development, system administration, and any field that requires log file analysis and management.

LogScribe MCP

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.