process-mcp

A local MCP (Model Context Protocol) server for managing background processes.

process-mcp lets AI assistants and other MCP clients start, stop, monitor, and query long-running shell commands without blocking the conversation. Instead of waiting for a command to finish, clients can start it in the background and receive a notification when it exits.

Features

• Start background processes with custom arguments, working directory, and environment variables

• Stop processes gracefully with SIGTERM or forcefully with SIGKILL

• Query real-time status and retrieve recent log output

• List all managed processes and resolve their system PIDs

• Receive process/exit notifications when a background process terminates

• Short, friendly process IDs via nanoid (6 characters)

• Strict input validation with zod

• Runs over stdio — no HTTP or SSE ports required

Related MCP server: MCP Background Job Server

Installation

Requires Bun.

bun install
bun run build

To run the server directly during development:

bun run dev

To run the compiled server:

bun run start

Configuration

Add process-mcp to your MCP client configuration. For opencode, edit ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "process-mcp": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/process-mcp/dist/index.js"
      ]
    }
  }
}

Adjust the absolute path to match your local clone location.

Tools Reference

start

Start a background process.

Parameters:

Example response:

{
  "id": "a1b2c3",
  "pid": 12345,
  "status": "running"
}

stop

Stop a managed process.

Parameters:

Example response:

{
  "id": "a1b2c3",
  "pid": 12345,
  "status": "stopped"
}

get-status

Get the current status of a process.

Parameters:

Returns: "running" | "stopped" | "exited" | "crashed" | "not-exists"

get-log

Retrieve the stdout/stderr log of a process.

Parameters:

Example response:

{
  "lines": [
    "Build started...",
    "Compiled 42 files",
    "Build finished"
  ]
}

list

List all managed processes.

Parameters: none

Example response:

{
  "processes": [
    { "id": "a1b2c3", "pid": 12345, "status": "running" },
    { "id": "d4e5f6", "pid": null, "status": "exited" }
  ]
}

get-pid

Get the system PID of a managed process.

Parameters:

Returns: PID number or null

Notification

When a process is started with notifyOnExit: true, the server sends a process/exit notification once the process terminates. The notification payload includes the process ID and final status.

This allows clients such as opencode to resume a conversation after a long-running task completes, without polling for status.

Development

Run the test suite:

bun test

Build the project:

bun run build

Run the server from source:

bun run dev

License

MIT