How do I use bg-tasks-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bg-tasks-mcp Start npm run dev as 'frontend' and monitor logs" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

bg-tasks-mcp

by rookie136

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

bg-tasks-mcp

Let your AI agent manage background processes. One sentence to start, monitor, and stop dev servers, builds, and tests — without leaving the conversation.

Why

Working on a full-stack project means juggling multiple terminal windows to start dev servers, check logs, and kill processes. Every context switch breaks your flow. You're the process manager, not the AI.

bg-tasks flips this: the LLM manages background processes for you.

Before:
┌──────────┐   ┌──────────────┐   ┌──────────────┐
│ opencode │   │ Terminal #1  │   │ Terminal #2  │
│ write code│   │ npm run dev  │   │ go run .      │
│ ask Q     │   │ check logs   │   │ check logs    │
└──────────┘   └──────────────┘   └──────────────┘
   ↑ Alt+Tab, manual PID hunting, context switching

After:
┌──────────────────────────────────────────────────┐
│ opencode                                         │
│                                                  │
│ "Start frontend and backend with bg-tasks"       │
│ → bg_start("frontend", "npm run dev")            │
│ → bg_start("backend", "go run .")               │
│                                                  │
│ "Show me frontend logs"                          │
│ → bg_logs(id="frontend", tail=20)                │
│                                                  │
│ "Stop the backend"                                │
│ → bg_kill(id="backend")                          │
│                                                  │
│ Dashboard: http://127.0.0.1:9876                 │
└──────────────────────────────────────────────────┘

Related MCP server: procm-mcp

Use Cases

Scenario	Example
Dev servers	`bg_start("fe", "npm run dev")` + `bg_start("be", "python app.py")`
Builds	`bg_start("build", "npm run build")` → `bg_wait("build")` → `bg_logs("build")`
Tests	`bg_start("test", "npm test")` → `bg_wait("test")`
Long scripts	`bg_start("seed", "node seed-db.js")` — check progress with `bg_logs`
Multi-project	Open two opencode windows → dashboard shows both projects' tasks

Installation

npm (recommended)

{"command": ["npx", "-y", "bg-tasks-mcp"]}

No install needed — npx downloads and runs on first use.

Manual install

npm install -g bg-tasks-mcp

Then configure:

{"command": ["bg-tasks-mcp"]}

Git clone

git clone https://github.com/rookie136/bg-tasks-mcp.git
cd bg-tasks-mcp
npm install

Then:

{"command": ["node", "/path/to/bg-tasks-mcp/index.js"]}

When you need to start, monitor, or stop background processes (dev servers, builds, tests),
use the bg-tasks tools.

Usage

6 MCP Tools

Tool	Purpose	Example
`bg_start`	Start a background task	`bg_start(name="frontend", command="npm run dev")`
`bg_wait`	Wait for completion or timeout	`bg_wait(id="frontend", timeout=30)`
`bg_logs`	Read task output	`bg_logs(id="frontend", tail=20, stream="stdout")`
`bg_status`	Inspect or list tasks	`bg_status(id="frontend")` / `bg_status()`
`bg_send`	Send text or signal	`bg_send(id="frontend", input="<Enter>")`
`bg_kill`	Terminate a task	`bg_kill(id="frontend")` / `bg_kill(id="frontend", force=true)`

5 MCP Resources

Resource	Description
`bg://status`	All tasks as JSON
`bg://{id}/status`	Single task detail + log summary
`bg://{id}/logs`	Combined stdout/stderr
`bg://{id}/logs/stdout`	stdout only
`bg://{id}/logs/stderr`	stderr only

Web Dashboard

When the first opencode window starts, the HTTP dashboard comes online automatically:

http://127.0.0.1:9876          English (default)
http://127.0.0.1:9876/?lang=zh 中文

Features:

Window list (owner PID, remote PIDs, task counts, last active time)
Real-time running tasks view
Clickable log links for remote window tasks
Per-window history with clear buttons
Bilingual UI (EN/中文 toggle)

Architecture

Multi-Window Design

┌─ opencode window #1 (owner) ──────────────────────────────────────┐
│  bg-tasks process                                                  │
│                                                                     │
│  serveStdio (MCP stdio)  ←─ LLM tool calls                         │
│  HTTP :9876                                                         │
│    GET /              → dashboard HTML (bilingual)                 │
│    GET /status        → JSON API                                   │
│    GET /logs/{id}     → log page                                   │
│    POST /api/report   → receive remote window tasks               │
│    GET /api/health    → liveness probe                             │
│                                                                     │
│  orphan check (30s) → parent alive? → 3 fails → self-terminate    │
└─────────────────────────────────────────────────────────────────────┘

┌─ opencode window #2 (non-owner) ───────────────────────────────────┐
│  bg-tasks process                                                  │
│                                                                     │
│  serveStdio (MCP stdio)  ←─ own LLM tool calls                    │
│  mini HTTP :9877                                                    │
│    GET /logs/{id} → log page (read-only)                          │
│                                                                     │
│  reporter → every 10s POST /api/report (:9876) push task state    │
│  health check → every 5s GET /api/health (:9876) → owner alive?   │
│    → takeover :9876 → become new owner → close mini HTTP           │
└─────────────────────────────────────────────────────────────────────┘

Owner/Takeover Lifecycle

Window #1 starts → binds :9876 → owner → dashboard online
Window #2 starts → EADDRINUSE → non-owner → mini HTTP :9877 → reporter push
Window #3 starts → EADDRINUSE → non-owner → mini HTTP :9878 → reporter push

Window #1 closes → health check fails → Window #2 jitter 500-1500ms → binds :9876
  → new owner → closes mini HTTP :9877 → tasks become local

Window #2 closes → Window #3 takes over
All windows closed → orphan check triggers → self-terminate

Data Flow

non-owner window                  owner window
─────────────────                 ─────────────
bg_start("server", ...)  ──┐
bg_start("client", ...)  ──┤
                              │
reporter (10s interval)  ◄────┘
  │
  │ POST /api/report { pid, port, tasks: [...] }
  ▼
owner dashboard ──► aggregates remote + local tasks
  │
  ├─ GET / → dashboard HTML (window list, running, history)
  ├─ GET /logs/{id} → local task logs (from MemoryLogStore)
  └─ remote task links → http://127.0.0.1:{port}/logs/{id} (mini HTTP)

Logging System

JSONL format written to <install-dir>/.log:

{"ts":"20260809T023839","evt":"owner_ok","pid":30508,"port":9876,"ppid":11972}
{"ts":"20260809T023900","evt":"bg_start","pid":30508,"id":"d26c6305","name":"backend","cmd":"python..."}
{"ts":"20260809T024200","evt":"bg_exit","pid":30508,"id":"d26c6305","exit":0,"ms":60000}
{"ts":"20260809T024503","evt":"orphan_check","pid":30508,"attempt":1,"alive":false}
{"ts":"20260809T030000","evt":"shutdown","pid":30508,"reason":"SIGTERM"}

Auto-rotation: 1MB per file, keeps last 2 backups (.log.0, .log.1).

i18n

Translations are JSON files in lib/i18n/. To add a new language, copy en.json to <lang>.json and translate the values.

lib/i18n/
├── en.json     # English (default, fallback)
└── zh.json     # 中文

File Structure

bg-tasks-mcp/
├── index.js              # entry: MCP stdio + owner detection + orphan check
├── lib/
│   ├── store.js           MemoryLogStore (ring buffer, 4MB per key)
│   ├── registry.js        TaskRegistry (state machine, onTaskEvent hook)
│   ├── platform.js        Windows/Unix adaptation (shell, kill, signal)
│   ├── session.js         session ID generation
│   ├── status-http.js     HTTP dashboard + routes + multi-window aggregation
│   ├── reporter.js        non-owner task state push (10s interval)
│   ├── logger.js          JSONL file logger (1MB rotation)
│   ├── i18n.js            i18n loader (in-memory cache, en fallback)
│   └── i18n/
│       ├── en.json         English translations
│       └── zh.json         中文翻译
├── tools/                 6 MCP tools (bg_start, bg_wait, bg_logs, etc.)
├── resources/             MCP resources (bg://status, bg://{id}/logs, etc.)
└── test/                  Node.js native test runner

Environment Variables

Variable	Description	Default
`BG_TASKS_NO_ORPHAN_CHECK`	Set to `1` to disable orphan detection	off

Platform

Node.js 18+, Windows/Linux/macOS. Windows uses taskkill instead of POSIX signals.

License

MIT

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

persistproc
irskep
A
license
Not graded
quality
D
maintenance
An MCP server that lets agents and humans monitor and control long-running processes, reducing copy-pasting between AI tools and enabling multiple agents to interact with the same process outputs.
Updated a year ago (2025-07-18 21:47 UTC)
8
MIT
procm-mcp
OS Automation Shell Access
coder-ka
A
license
C
quality
D
maintenance
An MCP server for secure process management, allowing LLMs to start, monitor, and manage whitelisted processes like development servers and test watchers.
Updated 3 months ago (2026-05-31 12:06 UTC)
11
28
5
MIT
process-mcp
Shell Access Command Line OS Automation
Kruceo
A
license
Not graded
quality
B
maintenance
An MCP server that allows AI assistants to manage background processes, enabling start, stop, monitoring, and querying of long-running shell commands without blocking the conversation.
Updated 3 months ago (2026-06-26 01:49 UTC)
MIT
Combined MCP Server
SMH01-MOD-NEXT
A
license
Not graded
quality
C
maintenance
A self-hosted MCP server that gives AI agents controlled access to a machine: filesystem, shell, background processes, git, web fetching and persistent key-value memory.
Updated 2 months ago (2026-07-17 12:47 UTC)
GPL 3.0

bg-tasks-mcp

Why

Use Cases

Installation

npm (recommended)

Manual install

Git clone

Usage

6 MCP Tools

5 MCP Resources

Web Dashboard

Architecture

Multi-Window Design

Owner/Takeover Lifecycle

Data Flow

Logging System

i18n

File Structure

Environment Variables

Platform

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

persistproc

procm-mcp

process-mcp

Combined MCP Server