logmcp

LogMCP

⚠️ IMPORTANT DISCLAIMER

This entire project was generated by AI without much human review or testing.
Use at your own risk. No warranty or support is provided.
The code may contain bugs, security vulnerabilities, or other issues.

By using this software, you acknowledge that:

• The code is 100% AI-generated
• It has not been designed for security or safety
• No support or maintenance is guaranteed
• You use it entirely at your own risk

A Model Context Protocol (MCP) server that provides log capture and process management for AI assistants like Claude. LogMCP allows AI tools to monitor, analyze, and interact with running processes through their log output.

What is LogMCP?

LogMCP bridges the gap between AI assistants and your running applications by:

• Log capture and buffering - Capture output from any process
• Process management - Start, stop, and control processes through AI
• Session buffering - Logs are buffered during active sessions
• Multi-process support - Track multiple applications simultaneously
• MCP integration - Works seamlessly with Claude Code and other MCP clients

Installation

Option 1: Download Pre-built Binary (Recommended)

Download the latest release for your platform from the releases page.

Or use the installation script:

# Install or update to latest version (installs to ~/.local/bin)
curl -sSL https://raw.githubusercontent.com/bebsworthy/logmcp/main/install.sh | bash -s -- -y

# Install or update to specific version
curl -sSL https://raw.githubusercontent.com/bebsworthy/logmcp/main/install.sh | bash -s -- -y 20240705143215

# Interactive installation (will prompt for confirmation)
curl -sSL https://raw.githubusercontent.com/bebsworthy/logmcp/main/install.sh -o install.sh && bash install.sh

Note:

• The same command both installs and updates LogMCP
• The install script installs to ~/.local/bin. If this directory is not in your PATH, add export PATH="$HOME/.local/bin:$PATH" to your shell configuration file.

Option 2: Install with Go

If you have Go 1.23+ installed:

go install github.com/bebsworthy/logmcp@latest

Option 3: Build from Source

git clone https://github.com/bebsworthy/logmcp
cd logmcp
go build -o logmcp .

Note: LogMCP automatically creates a new release when code changes are pushed to the main branch, versioned by timestamp (YYYYMMDDHHMMSS). Documentation-only changes do not trigger new releases.

Quick Start

The easiest way to use LogMCP is through an AI assistant like Claude Code, Cursor, or other MCP-compatible tools. Once configured, you can use natural language to monitor and control your applications.

1. One-Time Setup

Add LogMCP to your AI assistant:

For Claude Code (recommended):

# If installed with the install script or go install:
claude mcp add logmcp logmcp serve

# If installed elsewhere:
claude mcp add logmcp /path/to/logmcp serve

For other MCP tools:

Add to your MCP configuration file:

{
  "mcpServers": {
    "logmcp": {
      "command": "/path/to/logmcp",
      "args": ["serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Configuration file locations vary by tool:

• Claude Code: ~/.config/claude/mcp_servers.json (global) or .mcp.json (project-local)
• Other tools: Check your tool's documentation

That's it! Your AI assistant will now start LogMCP automatically when needed.

2. Start Using LogMCP

Just ask your AI assistant in natural language:

You: Use logmcp to start my React app and show me the logs
AI: I'll start your React development server with LogMCP and monitor its output...
     [Shows recent logs from npm start]

You: Also start the backend API with logmcp
AI: Starting your backend API server with LogMCP...
     [Shows logs from both frontend and backend]

You: Use logmcp to show me any errors in the frontend
AI: Looking at the LogMCP logs, I can see CORS errors when the frontend tries to call the API...
     [Provides specific error details and suggestions]

3. Common Commands You Can Use

• "Use logmcp to run my tests and show me the output" - Monitors test execution
• "Start all my services with logmcp" - Launches multiple processes
• "Use logmcp to show me the recent errors" - Searches logs for problems
• "Restart the backend using logmcp" - Controls running processes
• "Monitor the nginx log file with logmcp" - Watches existing log files

How It Works

When you ask your AI to run or monitor something:

1. The AI assistant automatically starts the LogMCP server (if not already running)
2. LogMCP executes your processes and captures their output
3. The AI can query recent logs to help you debug and understand what's happening
4. Logs are buffered during the session (up to 5MB or 5 minutes per process)

Manual Usage

If you prefer to use LogMCP directly from the command line without an AI assistant:

Start the Server

# Terminal 1: Start LogMCP server
logmcp serve

# Or with custom port
logmcp serve --websocket-port 9000

Run Processes with Monitoring

# Terminal 2: Run your application with log streaming
logmcp run --label "my-app" -- python my_script.py

# Run multiple processes (in separate terminals)
logmcp run --label "frontend" -- npm start
logmcp run --label "backend" -- python api.py
logmcp run --label "database" -- docker run postgres

Forward Existing Logs

# Forward from a log file
logmcp forward --label nginx /var/log/nginx/access.log

# Forward from stdin
tail -f /var/log/syslog | logmcp forward --label syslog

Note: When using manual mode, you need to keep the server running in one terminal while using other terminals for the run and forward commands.

Configuration (Optional)

LogMCP works with sensible defaults for most use cases. You only need to customize configuration for advanced scenarios.

Server Configuration

Create a config.yaml file if you need to customize settings:

server:
  host: "localhost"
  websocket_port: 8765
  mcp_transport: "stdio"

buffer:
  max_size: "5MB"
  max_age: "5m"

process:
  graceful_shutdown_timeout: "30s"
  cleanup_delay: "1h"

Environment Variables

You can also configure LogMCP using environment variables:

LOGMCP_CONFIG_FILE=/path/to/config.yaml
LOGMCP_HOST=localhost
LOGMCP_WEBSOCKET_PORT=8765
LOGMCP_VERBOSE=true

Use Cases

Development Workflow

# Start your development stack with LogMCP
./logmcp run --label "frontend" -- npm run dev
./logmcp run --label "backend" -- python manage.py runserver  
./logmcp run --label "db" -- docker-compose up postgres

# Claude can now monitor all services and help debug issues

CI/CD Integration

# In your CI pipeline
./logmcp run --label "tests" -- pytest --verbose
./logmcp run --label "build" -- docker build .
./logmcp run --label "deploy" -- kubectl apply -f k8s/

# AI can analyze build logs and deployment status

Production Monitoring

# Monitor production services
./logmcp run --label "api-server" -- ./my-api-server
./logmcp run --label "worker" -- celery worker
./logmcp run --label "scheduler" -- cron

# AI assistant can alert on errors and suggest fixes

RealHuman(TM) comment:
I didn't want to intervene but I need to mention that while it could technically work you'd be stupid to trust this tool in production. It has ABSOLUTELY ZERO security and the code might be absolute and utter garbage that will trash your servers, steal your cat and empty your bank account (I wouldn't know I purposedly didn't read it as an exercise); in any case it's most likely not robust enough to be running your production service. DON'T DO THAT !

Command Reference

logmcp serve

Start the LogMCP server for MCP clients.

./logmcp serve [flags]

Flags:
  --host string              Host to bind to (default "localhost")
  --websocket-port int       WebSocket port (default 8765)
  --config string           Config file path
  --verbose                 Enable verbose logging

logmcp run

Run a process with log streaming to LogMCP server.

./logmcp run [flags] -- <command>

Flags:
  --label string            Label for the process session
  --server-url string       LogMCP server URL (default "ws://localhost:8765")
  --working-dir string      Working directory for the process

logmcp forward

Forward logs from files or stdin to LogMCP server.

./logmcp forward [flags]

Flags:
  --label string            Label for the log session
  --server-url string       LogMCP server URL
  --file string            File to monitor (default: stdin)

Advanced Features

Session Persistence

• Logs persist for 1 hour after process termination
• AI can access historical logs even after reconnection
• Ring buffer prevents memory overflow (5MB/5min per session)

Multi-Client Support

• Multiple AI assistants can connect simultaneously
• Real-time log sharing across clients
• Concurrent process management

Error Handling

• Automatic reconnection on connection loss
• Graceful process termination
• Comprehensive error reporting to AI clients

Troubleshooting

Common Issues

LogMCP server won't start:

# Check if port is already in use
netstat -an | grep 8765

# Try a different port
./logmcp serve --websocket-port 9000

Claude Code can't find LogMCP:

• Verify the path in mcp_servers.json is absolute
• Ensure LogMCP binary has execute permissions
• Check Claude Code logs for connection errors

Processes not appearing in logs:

• Verify WebSocket connection: ws://localhost:8765
• Check firewall settings
• Ensure LogMCP server is running before starting processes

Debug Mode

Enable verbose logging for troubleshooting:

./logmcp serve --verbose
./logmcp run --verbose --label "debug" -- your-command

Contributing

We welcome contributions! Please see our contributing guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.