MCP Background Job Server

An MCP (Model Context Protocol) server that enables coding agents to execute long-running shell commands asynchronously with full process management capabilities.

Overview

The MCP Background Job Server provides a robust solution for running shell commands in the background, allowing agents to start processes, monitor their status, interact with them, and manage their lifecycle. This is particularly useful for development workflows involving build processes, test suites, servers, or any long-running operations.

Features

• Asynchronous Process Execution: Execute shell commands as background jobs with unique job IDs
• 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: Configurable job limits and automatic cleanup of completed processes
• MCP Protocol Integration: Full integration with 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 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 .
   

Quick Start

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"