MCP Background Job

The MCP Background Job Server lets you run long-running shell commands in the background with full control over the process lifecycle. It supports starting jobs, tracking progress, streaming output, and interacting with running processes, which is ideal for builds, tests, servers, and other time-consuming tasks that you want to manage from an MCP-enabled client.

How to use

You interact with the server through an MCP client to start, monitor, and control background processes. Start a new job by sending a request with the command you want to run. You receive a job identifier (job_id) that you use to check status, fetch recent output, or send input. You can tail stdout/stderr to observe progress in real time, interact by sending data to stdin, and terminate a job when you are finished.

How to install

Prerequisites you need before installing:

• Python 3.12 or higher
• uv package manager (used to install and run MCP servers)

# Quick install and run the MCP server
uvx mcp-background-job

Claude Code configuration can be set up so your editor launches the server as an MCP source. Use either the desktop integration or a configuration file.

# Option A: Claude Code Desktop
# Add a new MCP server named: background-job
# Command: uvx
# Args: ["mcp-background-job"]

# Option B: Configuration file
{
  "mcpServers": {
    "background-job": {
      "command": "uvx",
      "args": ["mcp-background-job"]
    }
  }
}

For development or local testing, you can run the server directly in stdio transport or via development mode.

# Run with stdio transport (most common)
uvx mcp-background-job

# Or for development
uv run python -m mcp_background_job

Configuration and environment

Configure runtime behavior with environment variables. The following options control concurrency, output buffering, timeouts, cleanup, and security-related restrictions.

# Maximum concurrent jobs (default: 10)
export MCP_BG_MAX_JOBS=20

# Maximum output buffer per job (default: 10MB)
export MCP_BG_MAX_OUTPUT_SIZE=20MB
# or in bytes:
export MCP_BG_MAX_OUTPUT_SIZE=20971520

# Default job timeout in seconds (default: no timeout)
export MCP_BG_JOB_TIMEOUT=3600

# Cleanup interval for completed jobs in seconds (default: 300)
export MCP_BG_CLEANUP_INTERVAL=600

# Working directory for jobs (default: current directory)
export MCP_BG_WORKING_DIR=/path/to/project

# Allowed command patterns (optional security restriction)
export MCP_BG_ALLOWED_COMMANDS="^npm ,^python ,^echo ,^ls"

Additional usage and examples

Basic operations you can perform with an MCP client: start a long-running command, check its status, retrieve recent output, interact with the process by sending input, and terminate when needed.

# Start a long-running command
# Job ID is returned by the execute action

# Check status periodically

Troubleshooting and notes

If you encounter issues, verify installation steps were completed, ensure the server runs with the required transport, and confirm environment variable values are set as intended. Large outputs may require adjusting MCP_BG_MAX_OUTPUT_SIZE.

Security considerations

Each job runs in its own subprocess, isolating processes. Apply resource limits, validate inputs, and consider an allowlist for commands in production to reduce risk.

Examples

Development server workflow and long-running tasks are demonstrated in practical usage snippets. You can start a server process, monitor startup, verify readiness, then stop the process when appropriate.

Notes on transport

The MCP server supports stdio for local development and HTTP for remote access. When using stdio, ensure logging goes to stderr to avoid protocol conflicts.

Available tools

list

Return a summary list of all background jobs with their basic metadata.

status

Query the status of a specific job by its job_id.

output

Retrieve the complete stdout and stderr for a finished or running job.

tail

Fetch the most recent lines of output for a running or completed job.

execute

Start a new background job and receive a unique job_id for future interactions.

interact

Send input to a running job's standard input stream and receive output.

kill

Terminate a running job and return its final status.