mcp-background-job

The MCP Background Job Server lets you manage long-running shell commands as background jobs via the MCP protocol. You can start new background processes, monitor their status, stream or fetch output, interact by sending input, and terminate processes when needed. It exposes a set of MCP tools for read-only operations (list, status, output, tail) and interactive controls (execute, interact, kill), enabling agents to orchestrate complex workflows such as build pipelines, long-running tests, or dev servers with fine-grained control.

To use it, connect via an MCP client or Claude Code configuration. Start a new job with the execute tool by providing the command you want to run, then use status and tail to observe progress and outputs in real time. If you need to feed the running process, use interact to send input, and when finished, kill to terminate the job. The server provides a JobID that you can reference across the tool calls to manage the lifecycle of that specific process.

Prerequisites:

• Python 3.12 or higher
• uv package manager installed (https://docs.astral.sh/uv/)

Quick installation (recommended):

• Install the server from PyPI and run via uvx

# Install and run the MCP server
uvx mcp-background-job

Claude Code integration (add to configuration):

{
  "mcpServers": {
    "background-job": {
      "command": "uvx",
      "args": ["mcp-background-job"]
    }
  }
}

Development setup (local development):

Prerequisites

• Python 3.12+
• uv package manager

Setup steps

1. Clone the repository

git clone https://github.com/dylan-gluck/mcp-background-job.git
cd mcp-background-job

2. Install dependencies and run in development mode

uv sync
uv add -e .

You can then run the server for development using uvx or uv run python -m mcp_background_job depending on your workflow.

Environment variables to tune behavior (examples):

• MCP_BG_MAX_JOBS: Maximum concurrent jobs (default 10)
• MCP_BG_MAX_OUTPUT_SIZE: Maximum output per job (default 10MB)
• MCP_BG_JOB_TIMEOUT: Default job timeout in seconds (default none)
• MCP_BG_WORKING_DIR: Working directory for jobs
• MCP_BG_ALLOWED_COMMANDS: Optional regex to restrict allowed commands for security

Configuration via Claude Code or JSON config files can override environment variables by setting an env map under the background-job server. Ensure you restart the MCP server after changing environment variables. If you encounter issues with long-running processes, check the container or host resource limits and verify the allowed command patterns if you enabled restrictions.