home / mcp / background process mcp server

Background Process MCP Server

Provides background process management via MCP: start, stop, monitor, and fetch output from long-running commands.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "waylaidwanderer-background-process-mcp": {
      "command": "npx",
      "args": [
        "@waylaidwanderer/background-process-mcp@latest",
        "--port",
        "31337"
      ]
    }
  }
}

You can manage long-running command-line processes from an MCP client using the Background Process MCP Server. It lets you start, monitor, and stop background tasks, giving you a consistent interface across agents and tools that may not natively support long-running processes.

How to use

Connect to a running Background Process MCP Server from your MCP client and use the provided tools to start new processes, monitor their output, and stop them when needed. You can start tasks in the background, fetch recent output, list all active and completed processes, and query the server status to ensure everything is healthy.

How to install

Prerequisites: You need Node.js and npm or a compatible package manager installed on your system.

1) Install the MCP server client package locally or globally using a standard config snippet.

{
  "mcpServers": {
    "backgroundProcess": {
      "command": "npx",
      "args": [
        "@waylaidwanderer/background-process-mcp@latest"
      ]
    }
  }
}

Additional usage notes

To connect to a standalone server, include the port in the arguments when you start the server. For example, you can specify a port like 31337 by adding "--port" and the port number to the arguments array.

You may run the MCP server using a package manager or a global install. Common approaches include using npx or installing the package globally and calling the provided command.

Available tools

start_process

Starts a new background process with the given command and returns a process identifier that you can use to manage it later.

stop_process

Stops a running background process using its unique process identifier.

clear_process

Removes a stopped process from the internal list and history.

get_process_output

Fetches recent output for a specific process. You can request the first N lines (head) or the last N lines (tail) of the output.

list_processes

Returns a JSON array describing the state of all managed processes, including their IDs, status, and basic metadata.

get_server_status

Provides current server status information such as version, port, PID, uptime, and counts of processes in different states.