Background Process MCP

A Model Context Protocol (MCP) server that provides background process management capabilities. This server enables LLMs to start, stop, and monitor long-running command-line processes.

Motivation

Some AI agents, like Claude Code, can manage background processes natively, but many others can't. This project provides that capability as a standard tool for other agents like Google's Gemini CLI. It works as a separate service, making long-running task management available to a wider range of agents. I also added a TUI because I wanted to be able to monitor the processes myself.

Screenshot

Getting Started

To get started, install the Background Process MCP server in your preferred client.

Standard Config

This configuration works for most MCP clients:

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

To connect to a standalone server, add the --port argument to the args array (e.g., ...mcp@latest", "--port", "31337"]).

<details>
<summary>Claude Code</summary>

Use the Claude Code CLI to add the Background Process MCP server:

claude mcp add backgroundProcess npx @waylaidwanderer/background-process-mcp@latest

<details>
<summary>Claude Desktop</summary>

Follow the MCP install guide, use the standard config above.

</details>

<details>
<summary>Codex</summary>

Create or edit the configuration file ~/.codex/config.toml and add:

[mcp_servers.backgroundProcess]
command = "npx"
args = ["@waylaidwanderer/background-process-mcp@latest"]

For more information, see the Codex MCP documentation.

</details>

<details>
<summary>Cursor</summary>

Click the button to install:

Or install manually:

Go to Cursor Settings -> MCP -> Add new MCP Server. Name it backgroundProcess, use command type with the command npx @waylaidwanderer/background-process-mcp@latest.

</details>

<details>
<summary>Gemini CLI</summary>

Follow the MCP install guide, use the standard config above.

</details>

<details>
<summary>Goose</summary>

Click the button to install:

Or install manually:

Go to Advanced settings -> Extensions -> Add custom extension. Name it backgroundProcess, use type STDIO, and set the command to npx @waylaidwanderer/background-process-mcp@latest. Click "Add Extension".
</details>

<details>
<summary>LM Studio</summary>

Click the button to install:

Or install manually:

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.
</details>

<details>
<summary>opencode</summary>

Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "backgroundProcess": {
      "type": "local",
      "command": [
        "npx",
        "@waylaidwanderer/background-process-mcp@latest"
      ],
      "enabled": true
    }
  }
}

<details>
<summary>Qodo Gen</summary>

Open Qodo Gen chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.

Click Save.
</details>

<details>
<summary>VS Code (for GitHub Copilot)</summary>

Click the button to install:

Or install manually:

Follow the MCP install guide, use the standard config above. You can also install the server using the VS Code CLI:

```bash