MCP Background Job

🚀 MCP Background Job Server

The MCP Background Job Server is an MCP (Model Context Protocol) server that allows coding agents to execute long - running shell commands asynchronously. It comes with full process management capabilities, addressing the need for handling long - running operations in development workflows.

✨ Features

• Asynchronous Process Execution: Execute shell commands as background jobs, each with a unique job ID.
• Process Lifecycle Management: Start, monitor, interact with, and terminate background processes.
• Real - time Output Monitoring: Capture and retrieve stdout/stderr, with buffering and tailing capabilities.
• Interactive Process Support: Send input to running processes via stdin.
• Resource Management: Configure job limits and automatically clean up completed processes.
• MCP Protocol Integration: Fully integrated with the Model Context Protocol for agent interactions.

📦 Installation

Quick Install (Recommended)

Install directly from PyPI using uvx:

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

Claude Code Integration

Add the server to your Claude Code configuration:

1. Option A: Using Claude Code Desktop

   • Open Claude Code settings/preferences.
   • Navigate to the MCP Servers section.
   • Add a new server:
     • Name: background - job
     • Command: uvx
     • Args: ["mcp-background-job"]

2. Option B: Configuration File Add to your Claude Code configuration file:

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

3. Restart Claude Code to load the new MCP server.

Development Setup

For local development or contributing:

Prerequisites

• Python 3.12 or higher
• uv package manager

Setup Steps

1. Clone and navigate to the project directory:

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

2. Install dependencies:

uv sync

3. Install in development mode:

uv add -e .

💻 Usage Examples

Basic Usage

# 1. Execute a long-running command
execute_result = await execute_command("npm run dev")
job_id = execute_result.job_id

# 2. Check job status
status = await get_job_status(job_id)
print(f"Job status: {status.status}")

# 3. Get recent output
output = await tail_job_output(job_id, lines=20)
print("Recent output:", output.stdout)

# 4. Interact with the process
interaction = await interact_with_job(job_id, "some input\n")
print("Process response:", interaction.stdout)

# 5. Kill the job when done
result = await kill_job(job_id)
print(f"Kill result: {result.status}")

Using with Claude Code

Once configured, ask Claude to help you with background tasks:

You: "Start my development server in the background and monitor it"

Claude: I'll start your development server using the background job server.

[Uses the execute tool to run your dev server]
[Shows job ID and monitors startup progress]
[Provides status updates]

Claude: "Your development server is now running on http://localhost:3000. 
The job ID is abc123 - def456 if you need to control it later."

Manual Server Usage

For development or direct usage:

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

# Or for development:
uv run python -m mcp_background_job

📚 Documentation

MCP Tools Reference

The server exposes 7 MCP tools for process management:

Read - only Tools

Interactive Tools

Job Status Values

• running - Process is currently executing
• completed - Process finished successfully
• failed - Process terminated with error
• killed - Process was terminated by user

Configuration

Environment Variables

Configure the server behavior using these environment variables:

# 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"

Claude Code Configuration with Environment Variables

{
    "mcpServers": {
        "background-job": {
            "command": "uvx",
            "args": ["mcp-background-job"],
            "env": {
                "MCP_BG_MAX_JOBS": "20",
                "MCP_BG_MAX_OUTPUT_SIZE": "20MB"
            }
        }
    }
}

Programmatic Configuration

from mcp_background_job.config import BackgroundJobConfig

config = BackgroundJobConfig(
    max_concurrent_jobs=20,
    max_output_size_bytes=20 * 1024 * 1024,  # 20MB
    default_job_timeout=7200,  # 2 hours
    cleanup_interval_seconds=600  # 10 minutes
)

Architecture

The server is built with a modular architecture:

• JobManager: Central service for job lifecycle management
• ProcessWrapper: Abstraction layer for subprocess handling with I/O buffering
• FastMCP Server: MCP protocol implementation with tool definitions
• Pydantic Models: Type - safe data validation and serialization

Key Components

src/mcp_background_job/
├── server.py          # FastMCP server and tool definitions
├── service.py         # JobManager service implementation  
├── process.py         # ProcessWrapper for subprocess management
├── models.py          # Pydantic data models
├── config.py          # Configuration management
└── logging_config.py  # Logging setup

Examples

Development Server Workflow

# Start a development server
job_id=$(echo '{"command": "npm run dev"}' | mcp-tool execute)

# Monitor the startup
mcp-tool tail --job_id "$job_id" --lines 10

# Check if server is ready
mcp-tool status --job_id "$job_id"

# Stop the server
mcp-tool kill --job_id "$job_id"

Long - running Build Process

# Start a build process
job_id=$(echo '{"command": "docker build -t myapp ."}' | mcp-tool execute)

# Monitor build progress
while true; do
  status=$(mcp-tool status --job_id "$job_id")
  if [[ "$status" != "running" ]]; then break; fi
  mcp-tool tail --job_id "$job_id" --lines 5
  sleep 10
done

# Get final build output
mcp-tool output --job_id "$job_id"

Interactive Process Example

# Start Python REPL
job_id=$(echo '{"command": "python -i"}' | mcp-tool execute)

# Send Python code
mcp-tool interact --job_id "$job_id" --input "print('Hello, World!')\n"

# Send more commands
mcp-tool interact --job_id "$job_id" --input "import sys; print(sys.version)\n"

# Exit REPL
mcp-tool interact --job_id "$job_id" --input "exit()\n"

Troubleshooting

Common Issues

• Import Errors: Ensure the package is installed in development mode:

uv add -e .

• Tests Not Running: Install the package first, then run tests:

uv sync
uv add -e .
uv run pytest tests/

• Permission Errors: Ensure proper permissions for the commands you're trying to execute.
• Memory Issues: Adjust MCP_BG_MAX_OUTPUT_SIZE if dealing with processes that generate large amounts of output.

🔧 Technical Details

The MCP Background Job Server is designed to handle asynchronous shell command execution. It uses a modular architecture with components like JobManager for job lifecycle management, ProcessWrapper for subprocess handling, and a FastMCP Server for MCP protocol implementation. The use of Pydantic Models ensures type - safe data validation and serialization.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

v0.1.1

• Published to PyPI for easy installation via uvx.
• Added console script entry point (mcp-background-job).
• Updated documentation with installation and usage instructions.
• Fixed linting issues and improved code quality.

v0.1.0

• Initial implementation with full MCP tool support.
• Process lifecycle management.
• Configurable resource limits.
• Comprehensive test suite.

Built with ❤️ using FastMCP and Python 3.12+