Process Manager MCP

Manage long-running bash processes and persist their logs.

GitHub

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

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>

# 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.

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

Related Servers