MCP Background Task Server

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 background
• Task 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 task
• shell (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 task
• data (string): Data to send to stdin

Installation

1. Clone this repository:

2. Install dependencies:

3. 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

1. Development Server: Start a development server and monitor its output
   run-background-task: name="dev-server", shell="npm run dev"
2. Build Process: Run a long build process and check its progress
   run-background-task: name="build", shell="npm run build:watch"
3. 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"
4. 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 mode
• pnpm run build: Build for production
• pnpm run type-check: Run TypeScript type checking
• pnpm 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Troubleshooting

Common Issues

1. Task not starting: Check if the shell command is valid and executable
2. No output: Some commands may not produce output immediately; check stderr as well
3. 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.