PM-MCP (Process Manager MCP)

A Model Context Protocol (MCP) server that allows Claude and other LLMs to manage long-running bash processes. Perfect for managing development servers, build processes, and other background tasks during development sessions.

Features

• Start Processes: Launch long-running bash commands with names and descriptions
• Process Management: Terminate individual processes or all processes at once
• Log Management: Capture, retrieve, and search through stdout/stderr logs
• Process Interaction: Send input to running processes
• Failure Detection: Immediate error reporting for processes that fail to start
• CLI Tool: Standalone command-line interface for process management
• Persistent Logging: All process logs are saved to disk for later retrieval

Installation

npm install -g pm-mcp

Usage

As an MCP Server

Configure your MCP client to use this server:

{
  "mcpServers": {
    "pm-mcp": {
      "command": "npx",
      "args": ["pm-mcp"]
    }
  }
}

Available MCP Tools

1. start_process - Start a new process

   • name (required): Process name for identification
   • command (required): Bash command to execute
   • description (optional): Process description
   • cwd (optional): Working directory

2. terminate_process - Stop a specific process

   • id (required): Process ID to terminate

3. terminate_all_processes - Stop all managed processes

4. list_processes - List all processes

   • id (optional): Get info for specific process

5. get_logs - Retrieve process logs

   • id (required): Process ID
   • lines (optional): Number of recent lines

6. grep_logs - Search process logs

   • id (required): Process ID
   • pattern (required): Regex search pattern

7. send_input - Send input to running process

   • id (required): Process ID
   • input (required): Input string to send

8. clear_finished - Clear terminated/failed processes and their logs

CLI Tool

# Start a process
npx pm-mcp cli start "dev-server" "npm run dev" --description "Development server"

# List all processes
npx pm-mcp cli list

# Get logs
npx pm-mcp cli logs <process-id>

# Tail (follow) logs in real-time
npx pm-mcp cli tail <process-id>

# Start process and immediately tail logs
npx pm-mcp cli start "my-server" "npm run dev" --tail

# Search logs
npx pm-mcp cli grep <process-id> "error"

# Send input to process
npx pm-mcp cli input <process-id> "some input"

# Terminate process
npx pm-mcp cli terminate <process-id>

# Terminate all processes
npx pm-mcp cli terminate-all

Example Usage with Claude

Claude: I'll start your development servers for you.

User: Start a React dev server on port 3000 and an API server on port 8080

Claude: I'll start both servers for you.

[Uses start_process tool]
- Name: "react-dev"
- Command: "npm run dev"
- Description: "React development server on port 3000"

[Uses start_process tool]  
- Name: "api-server"
- Command: "npm run api:dev"
- Description: "API development server on port 8080"

Both servers are now running. You can check their logs or terminate them anytime.

User: Check if there are any errors in the React server

Claude: [Uses grep_logs tool with pattern "error"]
No errors found in the React server logs.

User: Send "q" to quit the API server

Claude: [Uses send_input tool]
Input "q" sent to the API server process.

Real-time Log Streaming

PM-MCP supports real-time log streaming (tailing) for monitoring process output as it happens:

Tail Command

# Follow logs in real-time for a running process
npx pm-mcp cli tail <process-id>

# Show last 10 lines first, then follow new output
npx pm-mcp cli tail <process-id> --lines 10

Features:

• Non-blocking file watching for real-time updates
• Shows process status and information before streaming
• Graceful exit with Ctrl+C (process continues running)
• Works with both running and terminated processes
• Shows recent logs first if requested

Start with Tail

# Start a process and immediately begin tailing its logs
npx pm-mcp cli start "dev-server" "npm run dev" --tail

# This is equivalent to:
npx pm-mcp cli start "dev-server" "npm run dev"
npx pm-mcp cli tail <process-id>

Use Cases:

• Development servers that need immediate feedback
• Build processes where you want to see output right away
• Long-running tasks where monitoring is important
• Debugging processes by watching their output in real-time

Note: When tailing stops (Ctrl+C), the original process continues running. Use terminate to stop the actual process.

Log Files

Process logs are stored in ./pm-mcp-logs/ directory with the format <process-id>.log. Each log entry includes:

• Timestamp
• Stream type (stdout/stderr)
• Log content

Development

# Build the project
npm run build

# Watch mode for development
npm run dev

# Run the MCP server
npm start

# Use the CLI
npx pm-mcp cli --help

Architecture

• ProcessManager: Core class handling process lifecycle, logging, and management
• MCP Server: Exposes process management functionality via MCP protocol
• CLI Tool: Standalone interface for direct process management
• Logging: Persistent file-based logging with timestamp and stream type tracking