Background Process MCP

What is Background Process MCP?

Background Process MCP is a Model Context Protocol server that provides background process management capabilities. It enables LLM agents to start, stop, and monitor long-running command-line processes, and includes a terminal UI (TUI) for manual monitoring.

How to use Background Process MCP?

Install the server via npx @waylaidwanderer/background-process-mcp@latest in any MCP client (Claude Code, Claude Desktop, Cursor, Gemini CLI, etc.). For a standalone server, add the --port argument. Alternatively, install globally (pnpm add -g @waylaidwanderer/background-process-mcp) and use the bgpm command to run the core service (bgpm server) or the TUI (bgpm ui --port <port_number>).

Key features of Background Process MCP

• Start, stop, and clear background processes by UUID.
• Retrieve process output with optional head/tail parameters.
• List all managed processes as a JSON array.
• Get server status (version, port, PID, uptime, process counts).
• Offers a standalone core service and a separate TUI client.

Use cases of Background Process MCP

• LLM agents (e.g., Gemini CLI) managing long-running build or test scripts.
• Developers monitoring multiple concurrent command-line processes via a TUI.
• Integrating background process management into custom MCP clients.

FAQ from Background Process MCP

What problem does this solve that native agent process management doesn’t?

Some AI agents like Claude Code can manage background processes natively, but many others (e.g., Gemini CLI) cannot. This project provides that capability as a standard MCP tool, making long-running task management available to a wider range of agents.

What runtime or dependencies are required?

The server uses node-pty for child process lifecycle management and runs as a Node.js application. It is distributed as an npm package and executed via npx or a global install.

Where does process data live?

The Core Service (src/server.ts) is a standalone WebSocket server that acts as the single source of truth for all process states. The MCP client connects to it, either spawning a new instance or attaching to an existing one.

What transport and authentication does it use?

The MCP server uses the standard STDIO transport for MCP communication. The underlying Core Service communicates over WebSocket. No authentication method is documented.

Can I use Background Process MCP without an MCP client?

Yes. You can run the core service manually with npx @waylaidwanderer/background-process-mcp server and connect a TUI client via npx … ui --port <port>. The core service is standalone, allowing other custom clients to be built.