Process Manager MCP Server

A Model Context Protocol (MCP) server that provides process management capabilities with persistent storage and log management.

⚠️ Security Warning

This MCP server allows AI agents to execute arbitrary commands on your machine. This poses significant security risks including:

• Execution of malicious commands
• Access to sensitive files and system resources
• Potential system compromise
• Data theft or destruction

Strongly recommended security measures:

• Run agents in containerized environments (Docker, Podman, etc.) with limited privileges
• Never run this server with elevated privileges (root/Administrator)
• Use in isolated development environments only
• Regularly audit process logs for suspicious activity
• Consider using read-only filesystem mounts where possible

Use at your own risk. The authors are not responsible for any damage caused by misuse of this software.

Features

• Dual Mode Operation: Works as both MCP server and standalone CLI tool
• Start Processes: Launch processes with configurable auto-shutdown behavior and custom working directories
• Environment Variables: Pass custom environment variables to processes
• Stop Processes: Stop processes by command name or PID
• Process Monitoring: Automatic health checks every 5 seconds
• Persistent Storage: Process information persists across server restarts
• Log Management: Capture and retrieve process logs with tail functionality
• Directory-based Organization: Organize processes by working directory using the CWD environment variable
• Flexible Path Support: Support for both absolute and relative paths in the cwd parameter
• CLI Mode: Command-line interface for manual process management with streaming logs

Installation

As a CLI tool

npm install -g @botanicastudios/process-manager-mcp
procman start "npm run dev"

Or run directly with npx:

npx @botanicastudios/process-manager-mcp

Claude Code

claude mcp add process-manager -s user -- npx -y @botanicastudios/process-manager-mcp

Into an MCP server config file

{
  "mcpServers": {
    "process-manager": {
      "command": "npx",
      "args": ["-y", "@botanicastudios/process-manager-mcp"],
      "env": {
        "CWD": "/Users/me/Code/myproject"
      }
    }
  }
}

env.CWD is optional

CLI Usage

The process manager can be used as a standalone CLI tool for managing processes:

Starting Processes

# Start a process and stream logs to stdout (Ctrl+C to stop)
npx @botanicastudios/process-manager-mcp start "npm run dev"

# Start a persistent background process
npx @botanicastudios/process-manager-mcp start --persist "npm run dev"

# Start a process in a specific directory
npx @botanicastudios/process-manager-mcp start --cwd ./server "npm run dev"

# Start a process with environment variables
npx @botanicastudios/process-manager-mcp start --env USER_ID=12345 --env USER_TOKEN=abcdef "node app.js"

# Combine multiple options
npx @botanicastudios/process-manager-mcp start --persist --cwd ./backend --env PORT=3000 --env NODE_ENV=production "npm start"

Managing Processes

# List all managed processes
npx @botanicastudios/process-manager-mcp list

# Stop a process by PID
npx @botanicastudios/process-manager-mcp stop 12345

# Stop all managed processes
npx @botanicastudios/process-manager-mcp stop all

# View logs for a process
npx @botanicastudios/process-manager-mcp logs 12345

# Stream logs in real-time
npx @botanicastudios/process-manager-mcp logs -t 12345

# View last 200 lines of logs
npx @botanicastudios/process-manager-mcp logs -n 200 12345

CLI Options

• -c, --cwd <path>: Set working directory for the process (start command)
• -p, --persist: Keep process running after CLI exits (start command)
• -e, --env <key=value>: Set environment variable (can be used multiple times) (start command)
• -t, --tail: Stream logs in real-time (logs command)
• -n, --num-lines <number>: Number of log lines to display (default: 100) (logs command)
• --help: Show help information
• --version: Show version number

Note: Use stop all to stop all managed processes at once.

MCP Server Configuration

Set the CWD environment variable to specify the working directory for process management:

export CWD=/path/to/your/project
npx -y @botanicastudios/process-manager-mcp

If CWD is not set, the current working directory will be used.

Shared Process Management

Processes started via the CLI are visible to the MCP server and vice versa. This allows AI agents and human operators to collaborate on process management:

• Start a process via CLI, manage it via MCP
• Start a process via MCP (AI agent), monitor it via CLI
• Shared process list and log access
• Unified process storage

MCP Server Tools

start_process

Start a new process with the given command.

Parameters:

• command (string, required): The command to execute
• auto_shutdown (boolean, optional, default: true): Whether to automatically shutdown the process when the MCP server stops
• cwd (string, optional): Working directory for the process. Supports relative paths like './server' or 'server' (relative to ${process.env.CWD || process.cwd()})
• env (object, optional): Environment variables to set for the process (e.g., { "USER_ID": "12345", "USER_TOKEN": "abcdef" })

Returns: Process PID as an integer

Examples:

{
  "command": "npm run dev",
  "auto_shutdown": false
}

{
  "command": "python app.py",
  "auto_shutdown": true,
  "cwd": "./backend"
}

{
  "command": "node server.js",
  "auto_shutdown": false,
  "env": {
    "PORT": "3000",
    "NODE_ENV": "production",
    "API_KEY": "your-api-key-here"
  }
}

Returns:

{
  "content": [
    {
      "type": "text",
      "text": "Process started successfully. PID: 12345"
    }
  ]
}

end_process

Stop a running process by PID.

Parameters:

• pid (number, required): The PID of the process to stop

Returns:

{
  "content": [
    {
      "type": "text",
      "text": "Process stopped successfully"
    }
  ]
}

Or on error:

{
  "content": [
    {
      "type": "text",
      "text": "Process not found or could not be stopped"
    }
  ],
  "isError": true
}

get_logs

Fetch logs for a specific process by PID.

Parameters:

• pid (number, required): The PID of the process to get logs for
• numLines (number, optional, default: 100): Number of lines to retrieve from the end of the log

Example:

{
  "tool": "get_logs",
  "parameters": {
    "pid": 12345,
    "numLines": 50
  }
}

Returns:

{
  "content": [
    {
      "type": "text",
      "text": "2024-01-01 12:00:00 Server started\n2024-01-01 12:00:01 Listening on port 3000..."
    }
  ]
}

list_processes

List all running processes for the current working directory.

Parameters: None

Example:

{
  "tool": "list_processes",
  "parameters": {}
}

Returns:

{
  "content": [
    {
      "type": "text",
      "text": "PID: 12345\nCommand: npm run dev\nStatus: running\nStarted: 2024-01-01T00:00:00.000Z\nAuto-shutdown: true\nWorking Directory: /home/user/project\n\nPID: 67890\nCommand: python server.py\nStatus: running\nStarted: 2024-01-01T00:01:00.000Z\nAuto-shutdown: false\nWorking Directory: /home/user/api"
    }
  ]
}

Or when no processes are running:

{
  "content": [
    {
      "type": "text",
      "text": "No processes are currently running."
    }
  ]
}

Resources

processes://processes

Lists all tracked running processes for the current working directory.

Returns: JSON array with process information including:

• key: Internal process key
• pid: Process ID
• command: Original command
• status: Current status (running, stopped, crashed)
• startTime: ISO timestamp of when the process started
• autoShutdown: Whether the process will be shut down with the server
• errorOutput: Error information if the process crashed
• pwd: Absolute path to the directory where the command was executed (e.g., /Users/user/project)

processes://processes/{pid}/logs?numLines={tail_length}

Retrieve logs for a specific process.

Parameters:

• pid: Process ID (required in the URL path)
• numLines (optional query parameter, default: 100): Number of lines to tail from the end of the log

Returns: Process logs as plain text

Example: processes://processes/12345/logs?numLines=50

Process Management

Auto-shutdown vs Persistent Processes

• Auto-shutdown processes (auto_shutdown: true): These processes are automatically terminated when the MCP server shuts down. Useful for development servers and temporary processes.

• Persistent processes (auto_shutdown: false): These processes continue running even after the MCP server stops. Useful for background services and long-running tasks.

Process Monitoring

The server automatically monitors all tracked processes every 5 seconds:

• Running: Process is active and responding
• Stopped: Process ended normally or was terminated
• Crashed: Process ended with a non-zero exit code

Log Storage

Process logs are stored in ~/.process-manager-mcp/logs/ and are organized by PID. Logs persist even when the MCP server is not running, allowing you to retrieve logs from previously started processes.

Usage Examples

Starting a Development Server

{
  "tool": "start_process",
  "parameters": {
    "command": "npm run dev",
    "auto_shutdown": true
  }
}

Starting a Background Service

{
  "tool": "start_process",
  "parameters": {
    "command": "python background_worker.py",
    "auto_shutdown": false
  }
}

Starting a Process in a Specific Directory

{
  "tool": "start_process",
  "parameters": {
    "command": "npm start",
    "auto_shutdown": true,
    "cwd": "./frontend"
  }
}

This will run npm start in the ./frontend directory relative to the current working directory.

Starting a Process with Environment Variables

{
  "tool": "start_process",
  "parameters": {
    "command": "node api-server.js",
    "auto_shutdown": true,
    "env": {
      "PORT": "8080",
      "DATABASE_URL": "postgres://localhost:5432/mydb",
      "JWT_SECRET": "your-secret-key"
    }
  }
}

Starting a Process with Both Directory and Environment

{
  "tool": "start_process",
  "parameters": {
    "command": "npm run dev",
    "auto_shutdown": false,
    "cwd": "./microservice",
    "env": {
      "SERVICE_NAME": "auth-service",
      "PORT": "3001",
      "NODE_ENV": "development"
    }
  }
}

Stopping a Process by PID

{
  "tool": "end_process",
  "parameters": {
    "pid": 12345
  }
}

Viewing Process Logs

Use the get_logs tool:

{
  "tool": "get_logs",
  "parameters": {
    "pid": 12345,
    "numLines": 50
  }
}

Or access the resource processes://processes/12345/logs?numLines=50 to get the last 50 lines of logs for process with PID 12345.

Listing All Processes

{
  "tool": "list_processes",
  "parameters": {}
}

Development

Building from Source

git clone <repository>
cd process-manager-mcp
npm install
npm run build

Running in Development Mode

npm run dev

License

MIT