Provides tools for executing and managing Node.js processes in the background, including running development servers, builds, and other Node.js commands with real-time monitoring of stdout/stderr.
Allows running npm commands (like 'npm run dev', 'npm run build:watch') as background tasks, with the ability to monitor output and manage the processes.
Enables executing arbitrary shell commands as background tasks with full control over process lifecycle, input/output streams, and termination.
MCP Background Task Server
A Model Context Protocol (MCP) server that enables running and managing long-running background tasks from within Claude Desktop or other MCP-compatible clients.
Features
Run Background Tasks: Execute long-running commands (like
npm run dev
, servers, builds) in the backgroundTask Management: Start, stop, and list running background tasks
Interactive Communication: Send data to task stdin and retrieve stdout/stderr output
Process Monitoring: Track task states, PIDs, and exit codes
Graceful Shutdown: Automatically cleanup all background processes when the server stops
Available Tools
run-background-task
Starts a new background task with a unique name.
Parameters:
name
(string): Unique identifier for the taskshell
(string): Shell command to run in background
stop-background-task
Stops a running background task by name.
Parameters:
name
(string): Name of the task to stop
list-background-tasks
Lists all currently running background tasks with their PIDs and states.
get-task-stdout
Retrieves the stdout output from a background task.
Parameters:
name
(string): Name of the task
get-task-stderr
Retrieves the stderr output from a background task.
Parameters:
name
(string): Name of the task
send-to-task-stdin
Sends data to the stdin of a running background task (useful for interactive commands).
Parameters:
name
(string): Name of the taskdata
(string): Data to send to stdin
Installation
Clone this repository:
Install dependencies:
Build the project:
Usage
Development
Production
Development with Inspector
Configuration
To use this MCP server with Claude Desktop, add it to your claude_desktop_config.json
:
Replace /path/to/mcp-bgtask
with the actual path to your project directory.
Example Use Cases
Development Server: Start a development server and monitor its output
run-background-task: name="dev-server", shell="npm run dev"Build Process: Run a long build process and check its progress
run-background-task: name="build", shell="npm run build:watch"Interactive Commands: Run interactive CLI tools and send input
run-background-task: name="cli-tool", shell="my-interactive-cli" send-to-task-stdin: name="cli-tool", data="user input\n"Log Monitoring: Monitor logs from running processes
get-task-stdout: name="dev-server" get-task-stderr: name="dev-server"
Architecture
The server is built using:
Model Context Protocol SDK: For MCP server implementation
Node.js Child Process: For spawning and managing background processes
Zod: For input validation and schema definition
TypeScript: For type safety and better development experience
Key Components
Child Class: Manages individual background processes with state tracking
Process Map: Maintains a registry of all running tasks
Signal Handlers: Ensures graceful cleanup on server termination
Development
Scripts
pnpm run start
: Run the server in development modepnpm run build
: Build for productionpnpm run type-check
: Run TypeScript type checkingpnpm run dev
: Run with MCP inspector for debugging
Testing
The project includes Vitest configuration for testing. Run tests with:
Error Handling
The server includes robust error handling for:
Duplicate task names
Missing tasks
Process communication failures
Stdin/stdout availability issues
Security Considerations
⚠️ Warning: This server can execute arbitrary shell commands. Only use it in trusted environments and be careful about what commands you run through it.
License
ISC
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
Troubleshooting
Common Issues
Task not starting: Check if the shell command is valid and executable
No output: Some commands may not produce output immediately; check stderr as well
Process not stopping: Some processes may need specific signals; the server uses SIGTERM by default
Debugging
Use the MCP inspector for debugging:
Then open the provided URL in your browser to inspect MCP communications.
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
A Model Context Protocol server that enables running and managing long-running background tasks (like development servers, builds) from within Claude Desktop or other MCP-compatible clients.
Related MCP Servers
- AsecurityAlicenseAqualityModel Context Protocol server for Task Management. This allows Claude Desktop (or any MCP client) to manage and execute tasks in a queue-based system.Last updated -10329194MIT License
- -securityFlicense-qualityA Model Context Protocol server built with mcp-framework that allows users to create and manage custom tools for processing data, integrating with the Claude Desktop via CLI.Last updated -145
- AsecurityAlicenseAqualityModel Context Protocol server that enables Claude Desktop (or any MCP client) to fetch web content and process images appropriately.Last updated -138MIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that allows Claude Desktop to manage and execute tasks in a queue-based system, supporting planning, execution, and completion phases.Last updated -103296MIT License