Skip to main content
Glama

MCP Background Job Server

by dylan-gluck
GitHub
Python
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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

Basic Usage Example

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

MCP Tools Reference

The server exposes 7 MCP tools for process management:

Read-only Tools

ToolDescriptionParametersReturns
listList all background jobsNone{jobs: [JobSummary]}
statusGet job statusjob_id: str{status: JobStatus}
outputGet complete job outputjob_id: str{stdout: str, stderr: str}
tailGet recent output linesjob_id: str, lines: int{stdout: str, stderr: str}

Interactive Tools

ToolDescriptionParametersReturns
executeStart new background jobcommand: str{job_id: str}
interactSend input to job stdinjob_id: str, input: str{stdout: str, stderr: str}
killTerminate running jobjob_id: str{status: str}

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

Development

Running Tests

# Run all tests uv run pytest tests/ # Run unit tests only uv run pytest tests/unit/ -v # Run integration tests only uv run pytest tests/integration/ -v

Code Formatting

# Format code with ruff uv run ruff format # Run type checking uv run mypy src/

Development Workflow

  1. Make your changes
  2. Run tests: uv run pytest tests/
  3. Format code: uv run ruff format
  4. Commit changes

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"

Security Considerations

  • Process Isolation: Each job runs as a separate subprocess
  • Resource Limits: Configurable limits on concurrent jobs and memory usage
  • Input Validation: All parameters are validated using Pydantic models
  • Command Restrictions: Consider implementing command allowlists in production
  • Output Sanitization: Be aware that process output may contain sensitive information

Transport Support

The server supports multiple MCP transports:

  • stdio: Default transport for local development and agent integration
  • HTTP: For remote access (requires additional setup)

For stdio transport, ensure logging goes to stderr only to avoid protocol conflicts.

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.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Run the test suite and formatting
  5. Submit a pull request

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+

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

An MCP server that enables coding agents to execute and manage long-running shell commands asynchronously with capabilities for process monitoring, interaction, and lifecycle management.

  1. Overview
    1. Features
      1. Installation
        1. Quick Install (Recommended)
        2. Claude Code Integration
        3. Development Setup
      2. Quick Start
        1. Using with Claude Code
        2. Manual Server Usage
        3. Basic Usage Example
      3. MCP Tools Reference
        1. Read-only Tools
        2. Interactive Tools
        3. Job Status Values
      4. Configuration
        1. Environment Variables
        2. Claude Code Configuration with Environment Variables
        3. Programmatic Configuration
      5. Architecture
        1. Key Components
      6. Development
        1. Running Tests
        2. Code Formatting
        3. Development Workflow
      7. Examples
        1. Development Server Workflow
        2. Long-running Build Process
        3. Interactive Process Example
      8. Security Considerations
        1. Transport Support
          1. Troubleshooting
            1. Common Issues
          2. Contributing
            1. License
              1. Changelog
                1. v0.1.1
                2. v0.1.0

              Related MCP Servers

              • MCP Shell Server

                mkusaka
                A
                security
                A
                license
                A
                quality
                A server that uses the Model Context Protocol (MCP) to allow AI agents to safely execute shell commands on a host system.
                Last updated -
                1
                20
                4
                TypeScript
                MIT License
                • Linux
                • Apple

              • Interactive Feedback MCP

                duolabmeng6
                A
                security
                A
                license
                A
                quality
                A powerful MCP server that provides interactive user feedback and command execution capabilities for AI-assisted development, featuring a graphical interface with text and image support.
                Last updated -
                1
                33
                Python
                MIT License

              • mcp-shell

                sonirico
                -
                security
                A
                license
                -
                quality
                Give hands to AI. MCP server to run shell commands securely, auditably, and on demand.
                Last updated -
                12
                Go
                MIT License
                • Linux
                • Apple

              • AI Agent Template MCP Server

                bswa006
                A
                security
                F
                license
                A
                quality
                An MCP server that enhances AI agents' coding capabilities by providing zero hallucinations, improved code quality, security-first approach, high test coverage, and efficient context management.
                Last updated -
                15
                70
                1
                TypeScript

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/dylan-gluck/mcp-background-job'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server