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

Clone this repository:

git clone <repository-url>
cd mcp-bgtask

Install dependencies:

pnpm install

Build the project:

pnpm run build

Usage

Development

pnpm run start

Production

pnpm run build
node dist/index.js

Development with Inspector

pnpm run dev

Configuration

To use this MCP server with Claude Desktop, add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "bgtask": {
      "command": "node",
      "args": ["/path/to/mcp-bgtask/dist/index.js"],
      "cwd": "/path/to/mcp-bgtask"
    }
  }
}

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

pnpm test

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:

pnpm run dev

Then open the provided URL in your browser to inspect MCP communications.