Skip to main content
Glama
nanoseil

MCP Background Task Server

by nanoseil
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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

Related MCP server: Claude MCP Command Server

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:

git clone <repository-url>
cd mcp-bgtask

  1. Install dependencies:

pnpm install

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

  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:

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

  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:

pnpm run dev

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

Available Tools

6 tools
get-task-stderrGet Task StderrB

Retrieves the stderr of a running background task.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesUnique name of the task

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool retrieves stderr, implying a read operation, but lacks details on permissions, rate limits, error handling, or what happens if the task isn't running. This leaves significant gaps for a tool interacting with background tasks.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (interacting with background tasks), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavior, error cases, or return format, leaving room for improvement in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, fully documenting the 'name' parameter as a unique task identifier. The description adds no additional semantic context beyond implying the task must be running, which is minimal value. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('retrieves') and resource ('stderr of a running background task'), making the purpose immediately understandable. It distinguishes from sibling tools like 'get-task-stdout' by specifying stderr, but doesn't explicitly contrast with other siblings like 'list-background-tasks' or 'stop-background-task'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides minimal guidance, stating it retrieves stderr for 'a running background task', which implies it should be used when a task is active. However, it offers no explicit when-not-to-use advice, prerequisites, or alternatives among siblings like 'get-task-stdout' for stdout or 'list-background-tasks' for task status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-task-stdoutGet Task StdoutB

Retrieves the stdout of a running background task.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesUnique name of the task

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Retrieves' implies a read operation, it doesn't specify whether this requires specific permissions, what happens if the task isn't running or doesn't exist, or any rate limits. For a tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple retrieval tool and front-loads the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read operation with no output schema, the description is minimally adequate but has clear gaps. It doesn't explain what format the stdout returns in, whether it's paginated, or what happens with non-existent tasks. The absence of annotations means the description should do more to compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the single parameter 'name' clearly documented as 'Unique name of the task' in the schema. The description doesn't add any additional parameter context beyond what the schema provides, so the baseline score of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieves') and resource ('stdout of a running background task'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'get-task-stderr' which retrieves stderr instead of stdout, missing an opportunity for sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that 'get-task-stderr' retrieves error output instead, or that 'list-background-tasks' might be needed first to identify task names. No usage context or exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-background-tasksList Background TasksA

Lists all currently running background tasks.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only states the basic action without disclosing behavioral traits like pagination, rate limits, permissions required, or output format. It fails to add meaningful context beyond the minimal purpose, leaving critical operational details unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose without any wasted words. It is appropriately sized for a simple tool with no parameters, earning its place by directly stating the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (listing tasks) and lack of annotations or output schema, the description is incomplete. It does not explain what information is returned (e.g., task IDs, statuses), how results are structured, or any limitations, leaving significant gaps for an AI agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately omits parameter details, aligning with the schema's completeness. A baseline of 4 is applied as it correctly avoids redundancy while maintaining clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Lists') and resource ('all currently running background tasks'), distinguishing it from siblings like get-task-stderr (retrieves error output) or run-background-task (initiates tasks). It precisely communicates the tool's function without redundancy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for monitoring active tasks but provides no explicit guidance on when to use this tool versus alternatives (e.g., to check task status vs. retrieving logs). It lacks context on prerequisites or exclusions, leaving usage inferred rather than clearly defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run-background-taskRun Background TaskA

Runs a long-running command (like 'npm run dev') in background. When the command is running, you can interact with it using other tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesUnique name of the task
shellYesShell command to run in background

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the command is 'long-running' and runs 'in background', which implies non-blocking execution and potential for interaction via other tools. However, it lacks details on permissions, error handling, rate limits, or what happens if a task with the same name exists, leaving behavioral gaps for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence and adds useful context in the second. Both sentences earn their place by clarifying the tool's role and interaction model without any wasted words, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description provides basic purpose and usage context but lacks details on behavioral aspects like error responses, task lifecycle, or output format. For a tool that initiates background processes, more information on success/failure indicators or long-running implications would improve completeness, though it's minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('name' and 'shell'). The description adds no additional meaning beyond implying 'shell' is for commands like 'npm run dev', but this is redundant with the schema's 'Shell command to run' description. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Runs') and resource ('a long-running command in background'), with specific examples like 'npm run dev'. It distinguishes from siblings by mentioning interaction with other tools, which implies this is the entry point for background execution versus monitoring/control tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('Runs a long-running command in background') and hints at alternatives by stating 'you can interact with it using other tools', which references sibling tools like get-task-stderr or stop-background-task. However, it doesn't explicitly name alternatives or specify when not to use it, such as for short commands or immediate execution.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send-to-task-stdinSend to Task StdinB

Sends data to the stdin of a running background task.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesUnique name of the task
dataYesData to send to the task's stdin

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions sending data to stdin but lacks details on behavioral traits such as whether this requires specific permissions, how data is processed, potential errors if the task isn't running, or rate limits, making it insufficient for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any wasted words, making it appropriately sized and front-loaded for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of interacting with a running task (a mutation operation) and the lack of annotations and output schema, the description is incomplete. It does not cover important aspects like response behavior, error handling, or prerequisites, leaving significant gaps for an AI agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('name' and 'data') adequately. The description adds no additional meaning beyond what the schema provides, such as format examples or constraints, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Sends data') and target resource ('to the stdin of a running background task'), distinguishing it from sibling tools like get-task-stderr, get-task-stdout, list-background-tasks, run-background-task, and stop-background-task which have different purposes (reading output, listing, starting, or stopping tasks).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying 'a running background task', suggesting it should only be used when a task is active, but it does not explicitly state when to use this tool versus alternatives (e.g., when to send data vs. reading output) or provide exclusions, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stop-background-taskStop Background TaskC

Stops a running background task by its name.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesUnique name of the task to stop

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('stops') but doesn't cover critical traits like whether this is destructive (likely yes, but not confirmed), permission requirements, side effects (e.g., task termination effects), or error handling. This leaves significant gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action, making it easy to parse and understand quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., what 'stop' entails, success/failure responses) and doesn't compensate for the absence of structured data, making it inadequate for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'name' parameter fully documented. The description adds no additional meaning beyond implying the name is used for identification, which the schema already covers. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('stops') and resource ('a running background task'), specifying it's done 'by its name'. However, it doesn't explicitly differentiate from sibling tools like 'list-background-tasks' or 'run-background-task' in terms of purpose, which would require a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as when a task should be stopped versus monitored or restarted. It lacks context about prerequisites (e.g., task must be running) or exclusions, offering only basic usage without strategic advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updates
    • First observedget-task-stderr
    • First observedget-task-stdout
    • First observedlist-background-tasks
    • First observedrun-background-task
    • First observedsend-to-task-stdin
    • First observedstop-background-task
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no ambiguity. The tools cover different aspects of background task management: listing, running, stopping, and interacting with stdin/stdout/stderr. There is no overlap in functionality.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with hyphens (e.g., run-background-task, list-background-tasks). The naming is predictable and readable throughout the set.

Tool Count5/5

With 6 tools, the count is well-scoped for managing background tasks. Each tool earns its place by covering essential operations like starting, stopping, monitoring, and interacting with tasks.

Completeness5/5

The tool set provides complete lifecycle coverage for background tasks: creation (run-background-task), monitoring (list-background-tasks, get-task-stdout, get-task-stderr), interaction (send-to-task-stdin), and termination (stop-background-task). No obvious gaps exist.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Tools

    ZbigniewTomanek
    A
    license
    Not graded
    quality
    D
    maintenance
    A custom Model Context Protocol server that gives Claude Desktop and other LLMs access to file system operations and command execution capabilities through standardized tool interfaces.
    23
    Apache 2.0

  • Claude MCP Command Server

    kimjungyeol
    F
    license
    Not graded
    quality
    D
    maintenance
    A server implementation for the Model Context Protocol (MCP) that allows Claude AI to execute commands through a command-line interface, enabling direct system interactions from within Claude.
    -