mcp-read-logs

ackertyson/mcp-read-logs

3.2

If you are the rightful owner of mcp-read-logs and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

An experimental MCP server for real-time log collection and analysis from various sources.

Tools

  1. read_log_slice

    Read specific sections of the collected logs.

  2. search_logs

    Search for regex patterns in the collected logs (case-insensitive).

MCP Read Logs

An MCP (Model Context Protocol) server that provides access to application logs through continuous log feeds. Currently supports Docker Compose, Docker, Kubernetes, local file watching, and Serena logs with a modular design for adding other log sources.

IMPORTANT: THIS PROJECT IS NOT INTENDED FOR PRODUCTION USE--IT IS AN EXPERIMENT.

Table of Contents

Features

  • Real-time log collection: Continuously collects logs from various sources (Docker Compose, Docker, Kubernetes, local files, Serena)
  • Log slicing: Read specific sections of logs with offset and size parameters
  • Regex log searching: Search for regex patterns within the collected logs (case-insensitive)

Tools

read_log_slice

Read a slice of the collected logs.

Parameters:

  • offset (number): Starting line offset (0-based)
  • size (number): Number of lines to read

search_logs

Search for a regex pattern in the collected logs (case-insensitive).

Parameters:

  • pattern (string): Regex pattern to search for in the logs (case-insensitive)

How It Works

  1. The server starts the appropriate log collection process for the configured source
  2. Log output is continuously collected in an in-memory buffer
  3. The MCP tools provide access to read slices of logs or search for patterns
  4. The server handles process cleanup on exit

Example Use Cases

Debugging Application Issues:

  • "Search for 'ERROR' in the logs to find recent errors"
  • "Show me logs from the last 50 lines to see what happened before the crash"
  • "Find all 500 status code responses in my web server logs"

Monitoring Application Performance:

  • "Search for 'slow query' patterns in database logs"
  • "Find requests that contain 'timeout' in the logs"
  • "Look for memory warnings or out-of-memory errors"

Development Workflow:

  • "Show me the latest logs to see if my changes deployed correctly"
  • "Search for my specific feature flag logs"
  • "Find startup messages to confirm all services initialized"

Security and Compliance:

  • "Search for failed authentication attempts"
  • "Find logs containing specific IP addresses"
  • "Look for unauthorized access patterns"

Installation

npm install
npm run build

Log Sources

Docker Compose

Monitors logs from Docker Compose services in real-time by executing docker compose logs -f.

Docker

Monitors logs from individual Docker containers in real-time by executing docker logs -f <container>.

Kubernetes

Monitors logs from Kubernetes resources (pods, deployments, services) in real-time by executing kubectl logs -f with specified arguments.

Local Files

Watches local log files for changes and streams new content in real-time using Node.js fs.watch(). Supports file truncation detection and efficient incremental reading.

Serena

Connects to Serena's REST API endpoint to poll for log messages. Serena is a coding agent that provides logs through a /get_log_messages endpoint.

Known Limitation: Currently hardcoded to localhost:24282. If Serena is running on a different host or port, the connection will fail. Future versions will support configurable host/port via CLI arguments or environment variables.

Usage

Claude Code

To use this MCP server with Claude Code, you can configure it using either the CLI or settings UI:

Option 1: CLI Configuration (Recommended)
# Docker Compose logs
claude mcp add compose-logs -- node /absolute/path/to/mcp-read-logs/build/index.js --compose /path/to/your/docker-compose.yml

# Docker logs
claude mcp add docker-logs -- node /absolute/path/to/mcp-read-logs/build/index.js --docker my-container

# Kubernetes logs
claude mcp add k8s-logs -- node /absolute/path/to/mcp-read-logs/build/index.js --kubernetes my-pod

# Local file logs
claude mcp add file-logs -- node /absolute/path/to/mcp-read-logs/build/index.js --file /var/log/app.log

# Serena logs
claude mcp add serena-logs -- node /absolute/path/to/mcp-read-logs/build/index.js --serena
Option 2: Settings UI Configuration
  1. Open Claude Code Settings: Use Cmd/Ctrl , or the settings menu
  2. Navigate to MCP Servers: Find the MCP configuration section
  3. Add this server configuration:
{
  "mcpServers": {
    "compose-logs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--compose", "/path/to/your/docker-compose.yml"],
      "description": "Access Docker Compose logs"
    },
    "docker-logs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--docker", "my-container"],
      "description": "Access Docker logs"
    },
    "k8s-logs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--kubernetes", "my-pod"],
      "description": "Access Kubernetes logs"
    },
    "file-logs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--file", "/var/log/app.log"],
      "description": "Access local file logs"
    },
    "serena-logs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--serena"],
      "description": "Access Serena logs"
    }
  }
}

VS Code

VS Code has built-in support for MCP servers through GitHub Copilot. You can configure this MCP server using a workspace-specific configuration file:

Workspace Configuration (Recommended)
  1. Create MCP configuration file: In your project root, create .vscode/mcp.json
  2. Add the MCP server configuration:
{
  "servers": {
    "composeLogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--compose", "./docker-compose.yml"]
    },
    "dockerLogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--docker", "my-container"]
    },
    "k8sLogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--kubernetes", "my-pod"]
    },
    "fileLogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--file", "/var/log/app.log"]
    },
    "serenaLogs": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-read-logs/build/index.js", "--serena"]
    }
  }
}

With MCP Inspector

You can test and interact with the server using the MCP Inspector:

# UI Mode (recommended) - Docker Compose
npx @modelcontextprotocol/inspector node build/index.js --compose /path/to/docker-compose.yml

# UI Mode - Docker
npx @modelcontextprotocol/inspector node build/index.js --docker my-container

# UI Mode - Kubernetes
npx @modelcontextprotocol/inspector node build/index.js --kubernetes my-pod

# UI Mode - Local file
npx @modelcontextprotocol/inspector node build/index.js --file /var/log/app.log

# UI Mode - Serena logs
npx @modelcontextprotocol/inspector node build/index.js --serena

# CLI Mode - Docker Compose
npx @modelcontextprotocol/inspector --cli node build/index.js --compose /path/to/docker-compose.yml

# CLI Mode - Docker
npx @modelcontextprotocol/inspector --cli node build/index.js --docker my-container

# CLI Mode - Kubernetes
npx @modelcontextprotocol/inspector --cli node build/index.js --kubernetes my-pod

# CLI Mode - Local file
npx @modelcontextprotocol/inspector --cli node build/index.js --file /var/log/app.log

# CLI Mode - Serena logs
npx @modelcontextprotocol/inspector --cli node build/index.js --serena localhost:24282

With Other MCP Clients

This server follows the standard MCP protocol and can be used with any MCP-compatible client. The general configuration pattern is:

{
  "command": "node",
  "args": ["path/to/build/index.js", "--compose", "path/to/docker-compose.yml"]
}

For other providers:

{
  "command": "node",
  "args": ["path/to/build/index.js", "--docker", "container-name"]
}

{
  "command": "node",
  "args": ["path/to/build/index.js", "--kubernetes", "pod-name"]
}

{
  "command": "node",
  "args": ["path/to/build/index.js", "--file", "/path/to/log/file"]
}

{
  "command": "node",
  "args": ["path/to/build/index.js", "--serena", "localhost:24282"]
}

Command Line Options

# Show help
./build/index.js --help

# Docker Compose (default docker-compose.yml in current directory)
./build/index.js --compose

# Docker Compose with specific file
./build/index.js --compose /path/to/docker-compose.yml

# Docker logs
./build/index.js --docker my-container

# Kubernetes logs
./build/index.js --kubernetes my-pod
./build/index.js --kubernetes deployment/my-app
./build/index.js --kubernetes -l app=myapp

# Local file logs
./build/index.js --file /var/log/app.log

# Serena logs (default localhost:24282)
./build/index.js --serena

# Serena logs with custom host/port
./build/index.js --serena localhost:12345

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run dev

# Run tests
npm test                    # Unit tests only
npm run test:integration    # MCP integration tests using Inspector CLI
npm run test:all            # Both unit and integration tests

# Clean build directory
npm run clean

Serena Integration

This project includes a serena-context.yaml file that configures Serena to use only its semantic (symbol-based) tools when working with this codebase. This leverages Serena's powerful semantic code analysis tools while leaving file- and regex-based operations to your IDE/agent's builtin tools.

To use Serena with Claude Code using this semantic-only context:

claude mcp add serena -- uv run --directory /path/to/serena serena-mcp-server --transport stdio --context /path/to/mcp-read-logs/serena-context.yaml

This configuration:

  • Excludes Serena's direct filesystem and regex tools (which Claude Code handles better)
  • Focuses on Serena's symbol-level semantic operations for precise code analysis
  • Provides complementary capabilities to Claude Code's built-in tools

Adding New Log Providers

The project uses a modular LogProvider strategy to support different log sources. The project includes built-in providers: DockerComposeProvider, DockerProvider, KubernetesProvider, FileProvider, and SerenaProvider. To add support for additional providers (e.g., systemd, journald, remote syslog):

  1. Extend the LogProvider abstract class (src/log-provider.ts):

    export class MyLogProvider extends LogProvider {
  async start(): Promise<void> { /* Start log collection */ }
  stop(): void { /* Stop and cleanup */ }
  async readSlice(options?: LogFetchOptions): Promise<string[]> { /* Fetch log slice */ }
  isStarted(): boolean { /* Return collection status */ }
  getSourceDescription(): string { /* Human-readable source description */ }
}

  2. Implement the required methods:

    • start(): Begin real-time log collection, emit data events for new log lines
    • stop(): Stop collection and clean up resources (processes, file handles, etc.)
    • readSlice(): Fetch log slice with optional filtering (tail, since, until)
    • isStarted(): Return whether log collection is currently active
    • getSourceDescription(): Return a description of the log source for debugging

  3. Emit events for log data and errors:

    • this.emit("data", logLine): New log line received
    • this.emit("error", errorMessage): Error during log collection
    • this.emit("exit", exitCode): Process/connection ended
    • this.emit("processError", error): Fatal error starting collection

  4. Update the CLI to accept new provider arguments and instantiate your provider

The LogManager class handles the provider lifecycle and maintains the log buffer, so providers only need to focus on their specific log source implementation.

Testing

This project includes comprehensive testing at multiple levels:

Unit Tests (npm test):

  • Core log processing and buffer management
  • MCP tool schema validation with Zod
  • Error handling and edge cases
  • Response format compliance

Integration Tests (npm run test:integration):

  • Uses MCP Inspector CLI to verify MCP protocol compliance
  • Tests tool registration and schema generation
  • Validates server responds correctly to MCP clients
  • Ensures tools are discoverable by Claude Code and other MCP clients

Acknowledgements

This project was authored largely by Claude Code, with human guidance and help from Serena. Initial project generation was performed using these resources for context: