MCP Background Task Server

You run and manage long‑running background tasks inside your MCP client using a dedicated Background Task MCP server. It lets you start tasks, monitor their status, stream stdout/stderr, and interact with processes in real time, all through MCP-enabled front ends.

How to use

You can start a new background task by giving it a unique name and a shell command to run in the background. You can stop tasks, list all running tasks, and fetch stdout or stderr to monitor progress. If a task requires interactive input, you can send data to its stdin and observe responses in real time. The server tracks each task by its name, PID, state, and exit code, and it cleans up all processes gracefully when you stop the server.

How to install

Prerequisites: Node.js and a package manager (npm or pnpm) must be available on your system.

# Clone the project
# Replace with the actual repository URL when available
git clone <repository-url>
cd mcp-bgtask

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run in development mode
pnpm run start

Configuration

To connect this MCP server to Claude Desktop, add a server entry that points to the local Node.js runtime and the built index file.

{
  "mcpServers": {
    "bgtask": {
      "command": "node",
      "args": ["/path/to/mcp-bgtask/dist/index.js"]
    }
  }
}

Security considerations

This server can execute arbitrary shell commands. Use it only in trusted environments and avoid exposing it to untrusted users or networks.

Troubleshooting

If a task does not start, verify that the shell command is valid and executable. If there is no immediate output, check both stdout and stderr for clues. Some processes may require specific signals to terminate; the server handles graceful shutdown to clean up running tasks.

Examples

Common use cases include starting a development server, running a long build, or interacting with a CLI tool that requires input.

Tools and endpoints

This MCP server exposes a set of tools that you can invoke from your MCP client to control and monitor tasks.

Available tools

run-background-task

Starts a new background task with a unique name by providing the task name and the shell command to run.

stop-background-task

Stops a running background task by its name.

list-background-tasks

Lists all currently running background tasks with their PIDs and states.

get-task-stdout

Retrieves the stdout output from a background task identified by its name.

get-task-stderr

Retrieves the stderr output from a background task identified by its name.

send-to-task-stdin

Sends data to the stdin of a running background task for interactive input.