watcher-mcp
Provides a Docker backend that pulls container images as background jobs, streaming logs unbuffered, flagging stalled pulls, enforcing job timeouts and returning a final report with exit code and duration.
Provides a Git backend that runs repository clones (and similar git operations) as supervised background jobs, with live log streaming, stall detection, bounded waits and a completion report.
Provides a Gradle backend for launching build tasks as background jobs, tracking the current step, seconds without output, exit code and duration, and notifying when the build finishes, fails or times out.
Provides an npm backend for installing Node packages as isolated background jobs, with unbuffered logs, stall watchdogs, timeouts and a report including installed versions.
Provides a pip backend (using uv when available) that installs Python packages from PyPI into isolated virtual environments as background jobs, reporting installed package versions, exit codes, per-step timings and relevant log lines.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
watcher-mcp
Servidor MCP que lanza y vigila trabajos largos: instalaciones, descargas, clones,
builds y tests. Cada trabajo corre en segundo plano y la llamada devuelve un job_id al
instante. La salida se guarda línea a línea, sin buffering. Un vigilante avisa por
notificación MCP si el proceso se queda en silencio (stalled) y cuando termina, con un
informe: éxito o fallo, código de salida, duración, versiones instaladas y líneas
relevantes del log. Ninguna espera es infinita: wait tiene un tope duro y cada
trabajo tiene un tiempo máximo (timed_out).
English: an MCP server that launches and watches long-running jobs (pip/uv, git, https downloads and binaries, npm, cargo, go, maven, gradle, brew, apt, docker pull, allowlisted build/test commands). It returns a job id immediately and streams unbuffered logs. A watchdog flags stalled processes, every wait is bounded, and an MCP notification carries a report when the job ends.

Por qué: la comparativa
Los agentes como Claude Code instalan con Bash + pip install. Si la instalación
tarda más que el límite de la herramienta (120 s), el agente se queda bloqueado. Luego
el comando pasa a segundo plano y el agente solo tiene un fichero de salida que debe
releer de vez en cuando. Ese fichero no le dice si el proceso sigue vivo o colgado,
ni cuándo terminó.
examples/compare.py hace las dos cosas con el mismo paquete:
slowpkg, un sdist local que tarda 25 s en compilar sin escribir nada, como cualquier
wheel que se compila desde el código fuente. Todas las cifras se miden en la propia
ejecución. Esta tabla sale de la grabación del GIF de arriba, hecha en un contenedor
Docker:
ANTES · Bash + pip | DESPUÉS · watcher-mcp | |
El agente recupera el control | a los 8 s (límite de Bash a escala; 120 s reales) | 0,04 s |
Durante la compilación ve… | el log congelado en | estado, pid, comando, segundos sin salida |
Aviso de atasco | ninguno |
|
Se entera de que terminó | por sondeo, 2,5 s tarde (y solo si sigue sondeando) | notificación al instante |
Llamadas del agente | 1 Bash + 5 sondeos ( | 2 ( |
Informe final | texto en bruto | exit code, versión instalada ( |
Con pip, el log no llega a estar vacío: pip escribe unas líneas y luego se calla
mientras compila. Con programas que acumulan stdout en un buffer (herramientas en C,
scripts de Python sin -u), el fichero sí queda vacío hasta el final.
watcher-mcp lo resuelve con io_mode = "pty". El test
test_buffered_program_pipe_vs_pty lo demuestra: por tubería,
0 líneas mientras el programa trabaja; con pty, en vivo.
Related MCP server: Agent Relay
Demos
Todas son ejecuciones reales del servidor por stdio (como lo lanza Claude Code),
grabadas en un contenedor Docker con scripts/make_demos.sh.
Las rutas del usuario se acortan a ~. En el GIF, las pausas largas se acortan; los
tiempos [ 12.3s] impresos son los reales. Cada demo tiene también su grabación
.cast (asciinema) y una captura PNG completa.
Atasco detectado y recuperado (stalled)
La compilación pasa 18 s sin escribir nada. A los 4 s llega el aviso stalled con el
pid, el comando y las últimas líneas. Cuando pip vuelve a escribir, el servidor avisa
de que se reanuda la salida y, al acabar, envía el informe.

Timeout global (timed_out)
Una compilación que no acabaría nunca, con job_timeout_s: 12. El servidor envía
SIGTERM al grupo de procesos y, si hace falta, SIGKILL. El aviso llega como error, y
la demo comprueba al final que el proceso ya no existe.

Instalación real desde PyPI (uv)

Fallo con informe
Un paquete que no existe: el informe trae el código de salida y las líneas de error relevantes, sin tener que leer el log entero.

Capturas completas: compare · stall · timeout · install · fail
Usado desde Claude Code
Registrado con claude mcp add (ver más abajo), Claude Code ve las tools
mcp__watcher-mcp__*. Esta es una ejecución real desde una sesión de Claude Code
(solo se acortan las rutas):
→ install(backend="pip", params={"packages": ["pypdf"], "venv": "claude-code-demo"})
← {"job_id": "718a09b210da", "state": "queued",
"summary": "pip install pypdf en ~/.local/state/watcher-mcp/venvs/claude-code-demo (vía uv)",
"next": "wait('718a09b210da', timeout_s=60) o logs('718a09b210da', tail=30). …"}
→ wait(job_id="718a09b210da", timeout_s=60)
← {"done": true, "report": {
"headline": "[718a09b210da] OK en 0.6s – pip install pypdf en ~/.local/state/watcher-mcp/venvs/claude-code-demo (vía uv) (pypdf 7.1.1, (python) 3.15.2)",
"state": "succeeded", "exit_code": 0, "duration_s": 0.645,
"steps": [{"name": "create-venv", "state": "ok", "exit_code": 0, "duration_s": 0.343, …},
{"name": "install", "state": "ok", "exit_code": 0, "duration_s": 0.262,
"command": ["uv", "pip", "install", "--no-progress", "--python", "…/bin/python", "--", "pypdf"]}],
"installed": {"pypdf": "7.1.1", "(python)": "3.15.2"},
"limits": {"job_timeout_s": 3600, "stall_timeout_s": 600, "io_mode": "pipe"},
"info": {"venv": "~/.local/state/watcher-mcp/venvs/claude-code-demo", "installer": "uv", …}}}Cómo funciona
flowchart LR
C["Cliente MCP<br/>(Claude Code)"] -- "install · status · logs<br/>wait · cancel · backends" --> S["server.py<br/>MCPServer"]
S -- "notifications/message<br/>resources/updated · progress" --> C
S --> J["jobs.py · núcleo<br/>cola · locks · límites<br/>watchdog · informe"]
J --> P["process.py<br/>exec sin shell · pipe/pty<br/>SIGTERM → SIGKILL"]
J --> B["backends/<br/>web: download · binary<br/>código: pip · git · npm · cargo · go · maven · gradle<br/>sistema: brew · apt · docker · run"]
J -. "output.log · job.json<br/>report.json" .-> D[("~/.local/state/<br/>watcher-mcp")]Backends como planificadores puros: un backend solo valida parámetros y devuelve un
Plancon argv explícitos. El núcleo ejecuta, registra, limita y notifica. Por eso añadir git, apt o curl no necesita tocar la cola, los logs ni la seguridad.Estados:
queued→running⇄stalled→succeeded|failed|cancelled|timed_out.Seguridad:
nada de
shell=True;se rechazan los valores que empiezan por
-;allowlist de backends;
sin
sudosalvo opt-in (y entoncessudo -n);rutas limitadas a raíces permitidas;
solo HTTPS;
redacción de tokens y contraseñas en logs, argv e informes.
Diseño completo en docs/design.md.
Instalación
Requiere Python 3.11+.
git clone https://github.com/Eliaxs1900/watcher-mcp.git
cd watcher-mcp
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e .Sin uv: python3 -m venv .venv && .venv/bin/pip install -e .
Registrarlo en Claude Code
Desde la carpeta del proyecto, para todos tus proyectos:
claude mcp add --scope user watcher-mcp -- "$PWD/.venv/bin/watcher-mcp"O solo para un proyecto, con un .mcp.json en su raíz:
{
"mcpServers": {
"watcher-mcp": {
"command": "/RUTA/ABSOLUTA/watcher-mcp/.venv/bin/watcher-mcp",
"args": ["--config", "/RUTA/ABSOLUTA/config.toml"]
}
}
}args es opcional; sin --config se usa ~/.config/watcher-mcp/config.toml si existe.
Comprueba que conecta con claude mcp list.
Tools
Tool | Para qué |
| Qué instaladores hay, si están permitidos, sus límites y el esquema de sus |
| Lanza el job y devuelve |
| Estado, paso actual, pid, comando, segundos sin salida, código de salida, duración, límites, informe. |
| Jobs recientes. |
| Últimas líneas; con |
| Espera acotada (60 s por defecto, tope duro 300 s): el informe, o "sigue en curso" con pid y últimas líneas. Emite |
| Cancela (SIGTERM y luego SIGKILL al grupo de procesos). |
Recursos: job://<id> (estado + informe) y jobs://list. Los avisos van a quien lanzó
el job (notifications/message, con el informe en data.report) y a quien esté
suscrito a job://<id> (notifications/resources/updated).
Backends
Cubren los focos de interacción habituales de un agente de código. Todos aceptan además
job_timeout_s y stall_timeout_s. backends() devuelve el esquema completo de cada uno.
Foco | Backend | Para qué | Ejemplo de |
Web |
| Fichero por HTTPS, checksum opcional, extracción segura de tar/zip |
|
Web |
| Ejecutable suelto (checksum obligatorio), también dentro de un tar/zip |
|
Código |
| Paquetes Python en un venv aislado (uv si está) |
|
Código |
| Clonar/actualizar (https, ssh, local) sin prompts de credenciales |
|
Código |
| Paquetes en un prefijo aislado, o dependencias de un proyecto (npm ci/pnpm/yarn) |
|
Código |
|
|
|
Código |
|
|
|
Código |
| Artefactos a |
|
Código |
| Tareas de un proyecto (allowlist) con |
|
Sistema |
| Fórmulas y casks sin auto-update ni prompts |
|
Sistema |
| apt-get (Debian/Ubuntu/WSL). Privilegiado: requiere |
|
Sistema |
|
|
|
Comandos |
| Builds y tests largos con un programa de una allowlist. Desactivado por defecto |
|
Por defecto están permitidos todos menos apt y run. Para activarlos:
allowed_backends = ["pip", "git", "download", "binary", "npm", "cargo", "go", "maven", "gradle",
"brew", "docker", "apt", "run"]
allow_privileged = true # solo si quieres apt (usa `sudo -n`: nunca pide contraseña)
[backends.run]
programs = ["mvn", "pytest", "make"] # lo único que `run` puede ejecutarLímites
Qué | Por defecto | Al vencer |
| 60 s ( |
|
Tiempo en cola | 3600 s ( |
|
Duración del job | 3600 s ( | SIGTERM al grupo, 5 s, SIGKILL; |
Sin salida | 300 s ( |
|
Se fijan por petición (pip: job_timeout_s, stall_timeout_s), por backend en la
configuración ([backends.pip] job_timeout_s = 1800) o globalmente.
Parámetros del backend pip
Param | Ejemplo | Notas |
|
| PEP 508 sin URLs; nada que empiece por |
|
| Alternativa o complemento a |
|
| Un nombre crea |
|
| Versión con uv (o |
|
|
|
|
| |
|
| Solo https; credenciales redactadas. |
|
| Instalación offline. |
|
| Al vencer: |
|
| Sin salida N s → |
Configuración
Ver examples/config.example.toml:
allowed_backends: la allowlist (por defecto solopip).allow_privileged:falsepor defecto.allowed_roots: dónde pueden escribir los backends.Límites:
max_parallel,default_wait_s,max_wait_s,max_queue_s,default_job_timeout_s,default_stall_timeout_s,default_io_mode.[backends.<nombre>]: límites eio_modepropios de un backend.plugins: backends externos, como"paquete.modulo:Clase".
WATCHER_MCP_STATE_DIR cambia el directorio de estado (por defecto
~/.local/state/watcher-mcp).
Tests y demos en Docker (sin ensuciar tu máquina)
docker build --target test -t watcher-mcp:test .
docker run --rm watcher-mcp:testSon 69 tests sin red:
núcleo: jobs en paralelo, logs en vivo, cancelación,
stalled,timed_out,waitacotado, pipe frente a pty, notificaciones de punta a punta por MCP y redacción de secretos;validación y plan de los 13 backends;
instalaciones reales offline: pip/uv con un wheel local, git con repos locales, descargas y binarios contra un servidor HTTPS local (checksum, extracción segura, redirección a http rechazada, atasco y cancelación) y
run.
Otros 6 hacen instalaciones reales contra internet (pip, git, download, apt, npm y go). Se ejecutan en su propio contenedor:
docker build --target integration -t watcher-mcp:integration .
docker run --rm watcher-mcp:integrationPara regenerar las demos (graban en un pty dentro del contenedor y renderizan GIF/PNG):
docker build --target demo -t watcher-mcp:demo .
docker run --name imcp-demos watcher-mcp:demo
docker cp imcp-demos:/out/. docs/demos/
docker rm imcp-demosSin Docker: uv pip install -e ".[dev]" y .venv/bin/python -m pytest -q. Las demos
también se pueden ejecutar directamente: python examples/demo.py stall,
python examples/compare.py.
Estructura
src/watcher_mcp/
server.py tools y recursos MCP, espera acotada con progreso
jobs.py núcleo: jobs, cola, límites, watchdog, logs, informe
process.py exec sin shell, lectura en vivo (pipe/pty/stdbuf), terminación acotada
notify.py eventos -> notifications/message, resources/updated, subscriptions/listen
security.py redacción, https, checksums, raíces permitidas
config.py configuración
backends/base.py interfaz Backend / Plan / CommandStep / FuncStep
backends/pip.py pip/uv backends/git.py git
backends/download.py download, binary backends/ecosystems.py npm, cargo, go
backends/jvm.py maven, gradle backends/system.py brew, apt, docker, run
backends/_template.py esqueleto para nuevos backends
docs/design.md diseño
docs/demos/ GIF, PNG y .cast de las demos
examples/ demos, comparativa, slowpkg, cliente mínimo y configuración
scripts/ grabación (pty -> .cast) y render (.cast -> GIF/PNG)
tests/ pytestLimitaciones
wsl(delegar un backend dentro de una distro) está diseñado pero no implementado.brew,cargo,maven,gradleydockertienen tests de validación y plan, pero no de instalación real en CI.Funciona en macOS y Linux (también WSL). En Windows nativo faltaría la cancelación por grupo de procesos.
Los jobs en curso no sobreviven a un reinicio del servidor: se marcan como interrumpidos.
Usa el SDK
mcp2.x (MCPServer, el sucesor de FastMCP).
Licencia
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Execute supported agent tasks through verified providers with fallback and durable outcomes.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Give your agent its own cloud: Postgres, Redis, a sandbox or any Docker image, in one MCP call.
Hosted coding agent: start, follow up on and stop tasks that can open GitHub pull requests.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables MCP clients to submit long-running jobs that are executed safely in isolated child processes with a durable SQLite queue, configurable timeouts, retries with backoff, and backpressure.5MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to asynchronously submit tasks to a persistent coding agent already running on a development machine, disconnect, and retrieve results later through a secure, policy-controlled gateway.MIT
- AlicenseAqualityBmaintenanceEnables MCP clients such as Claude Code, Codex, and Cursor to dispatch background subagent jobs to the Antigravity IDE's local agent engine and collect results asynchronously. Jobs run through the IDE's authenticated session without an API key, with optional Gemini REST fallback and on-disk job history.63MIT
- AlicenseAqualityBmaintenanceLets an MCP client hand coding tasks, second-opinion reviews, and image-asset generation to the official OpenAI CLI agent running locally, returning final messages, session IDs, and saved files. Jobs run sandboxed with prompts over stdin, work asynchronously with polling, and expose a live model catalog without needing an API key.5MIT