# mcproc MCP server

> Allows coding agents to control PM2 processes across local, SSH, and Docker hosts using a project-based manifest.

- Repository: https://github.com/kiwagu/mcproc
- Page: https://hostedmcp.org/servers/kiwagu/mcproc
- Transport: stdio
- Stars: 0
- License: MIT

## Install

### Claude Code

```sh
claude mcp add mcproc -- npx -y mcproc
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcproc": {
      "command": "npx",
      "args": [
        "-y",
        "mcproc"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcproc": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcproc"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcproc","type":"stdio","command":"npx","args":["-y","mcproc"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcproc": {
      "command": "npx",
      "args": [
        "-y",
        "mcproc"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add mcproc -- npx -y mcproc
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcproc]
command = "npx"
args = ["-y", "mcproc"]
```

### Gemini CLI

```sh
gemini mcp add -s user mcproc npx -- -y mcproc
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcproc": {
      "command": "npx",
      "args": [
        "-y",
        "mcproc"
      ]
    }
  }
}
```

## Tools (24)

- `hosts`: Hosts declared in the project manifest: transport, project cwd there, readonly flag. No network access. (read-only)
- `doctor`: Check hosts: reachable, Node version, which pm2 would run and why, ps/ss/tar availability, the unpacked runtime, daemon state, the host's environment (container, hostname) and where each app's url answers (on the host or from this machine). Recommends unpack, hosts.<host>.pm2 or pm2_home when pm2 is missing or unusable, and url_check: auto for an app with url_check: host whose url answers only from this machine. (read-only)
- `ls`: One row per manifest app, each from the host it runs on: pm2 status, pid, uptime, restarts, memory and CPU of the whole process tree, the runtime command, the ports it really listens on compared with the declared ones, and its URL with the HTTP answer (ok/error/down), requested on the app's host and, when the host gets no answer, from this machine: ✓ 200 (here), or ✗ down (refused) with the reason (url_check in the manifest pins one side). Answers "is it up, on which port, which address do I open". reloads: true also counts each running app's in-process reloads since its pm2 start (tsx/nodemon restarts, Vite/Next rebuilds, a repeated listening line), which pm2's restarts never show: RESTARTS 0 (+3), or 0 (+≥3) when the logs read did not reach back to the start. (read-only)
- `describe`: Call this first in a new session. Without app: project summary (apps with descriptions, profiles, hosts) plus .mcproc/README.md. With app: its manifest entry, runtime state, log paths, URL, ports and generated pm2 config. Without app it also lists the resolved vars with their sources and the override file, when the manifest declares vars. (read-only)
- `logs`: Read pm2 logs. One app, last N lines (default 100, max 2000) as out/err sections: pass app. Several apps since a point in time: pass targets (apps, profiles or ["all"]) and since: a span like 2m, a time like 2026-10-14T07:30 (the host's local time; add Z or +02:00 for an absolute instant), or last (everything since your previous logs call over those apps in this session). Lines come merged across apps in time order, each labelled `app | line` (`app ! line` for stderr), ANSI stripped; lines then caps the merged output (most recent kept). targets without since: the latest lines across the apps. After a change, read since over the profile instead of tailing each app. (read-only)
- `ports`: Who listens on which port on the host, including processes pm2 does not manage. With port: the holder of that port. (read-only)
- `wait`: Block until an app is usable or finished. until: listening (every declared port is bound), url-ok (its url answers 2xx/3xx), exited (the process left online; with autorestart off, kind task included, the answer carries exit_code and done / failed (exit N) / stopped, any other app shows pm2's stopped or errored), log:<regex> (a new line matches; tested without pm2's time stamp, ANSI stripped, the answer keeps the stamp), idle:<seconds> (no log output for that long), reloaded (the next in-process reload: tsx/nodemon restart, Vite/Next rebuild, a repeated listening line; answered once quiet for 2 s with its time, line count and first restart or rebuild line; for a server whose reload restarts it, wait until: listening next). log:, idle: and reloaded see only output written after the call begins, so to know whether the app is up prefer listening or url-ok. Refused (BAD_ARGUMENT): listening with no declared port, url-ok with no url, reloaded with reloads: false. ok false with what was last seen on timeout (default 60 s, max 600) or when the process died meanwhile; a result, not an error. A pm2 restart in progress is waited out. Call it after start instead of sleeping or polling ls. (read-only)
- `leases`: The host's memory lease queue: every lease with its state (pending, starting, running, freed, cancelled, failed), position, project and slot, target, estimate and need, where the estimate came from, what the head waits for; plus the host's memory reading and whether the watcher runs. A start that answered queued shows up here; wait on one of its apps to block until it is up. (read-only)
- `stacks`: Every mcproc stack on this host, not only this project: each checkout any mcproc call has seen or found in the local pm2 daemon, with its root, hosts, apps online/total, errors, memory, CPU and listening ports, plus pm2 processes no manifest knows. Use it to see what else runs here (another checkout holding a port or memory); act on another stack by passing its root as `project` to the other tools. (read-only)
- `incidents`: Only the errors that are NEW since they were last taken, each with lines of context before and after (a folded stack trace included), plus crashes and restarts. A call takes what it returns: the pick-up point, kept in .mcproc/incidents.json and shared by every session, agent and CLI call, moves past them, so nobody gets them twice; peek: true looks without taking. Take once you have dealt with them: the person's monit incidents screen shows taken ones muted. An answer carries about 20,000 characters of incidents, newest first; older ones past that are counted, not shown. A log clear (flush, or c in monit) starts incidents over from there. Cheap to poll: nothing new is one short line. During long work on running apps call it periodically, with your client's own loop/cron/monitor if it has one; read logs only for an incident worth a closer look. include_reloads: true adds each app's in-process reloads since the last call (tsx/nodemon restarts, Vite/Next rebuilds, a repeated listening line) as one reloaded incident per app with how many and when.
- `init`: Create .mcproc/ (gitignored) with a manifest DRAFT discovered from package.json scripts, workspaces, nx project.json, turbo.json, ecosystem.json and Procfile. On a turbo repo with a persistent dev task, the packages implementing it are drafted live (TODO descriptions to replace, a dev profile, libs/libs-watch builders for libraries consumed from dist/); every other candidate is commented out: uncomment, write descriptions, then verify with start + ls. Refuses to overwrite an existing manifest without force. With adopt_ports, instead write the ports ls reports as undeclared for the running apps into the existing manifest (comments kept) and return the diff; it needs that manifest, and force is ignored then.
- `start`: Start an app or profile via pm2 from the generated ecosystem, each app on the host it runs on, dependencies first. A dependency declared with condition ready or completed is waited for (up to its timeout) before the dependent starts, and a dependent whose dependency failed or timed out is skipped with the reason. Apps already online are left alone unless reload is true.
- `restart`: Restart the named app(s) with the current manifest config (command, env, watch).
- `stop`: Stop the named app(s); pm2 keeps them listed as stopped.
- `delete`: Remove the named app(s) from pm2 (stops them first).
- `lease_cancel`: Remove a pending lease from the host's queue (a start that has not been admitted yet), or a starting exec lease. A starting start or a running lease is refused: stop its target instead.
- `flush`: Truncate the pm2 log files of one app, or of every app of the project (each on the host it runs on; with host, the apps that run there). Incidents start over from the flush: nothing logged before it is reported again.
- `unpack`: Make a host self-sufficient: copy a pm2 tree (assembled once on this machine with npm from the lockfile mcproc ships; needs npm, tar and registry access the first time) and an official Node build when the host has no Node >= 18 (downloaded once from nodejs.org, checked against SHASUMS256), into <cwd>/.mcproc/runtime on that host or into dir, plus a copy of the manifest. Idempotent: same versions change nothing. Refused on readonly hosts and on a dir whose bin/ it did not write.
- `exec`: Run a one-off command (a test run, a build, a seed) from the project root on THIS machine with the manifest's exec.env (the stand's addresses, interpolated) and MCPROC_PROJECT set. With memory (e.g. "4G") it is a lease like a start: it runs at once when the host has room and the queue is empty, else waits its turn behind the pending leases (timeout_s, default 600, max 3600) and is freed when the command exits. With exclusive it runs in turn with the other runs of that group (timeout_s default 3600). Local host only; refused when the local host is readonly. Returns the exit code and the last 200 lines of output; isError when the code is not 0.
- `worktree_add`: Make an isolated checkout of this repository on a branch, in the sibling folder <repo>.worktrees/<branch>, with the files its own manifest's worktree: section (plus the main checkout's override) copies or links, its own slot (ports shifted by that manifest's vars), its slug (the project slug this checkout runs under, default <project>-w<slot>) and the install. A worktree.required entry missing in the main checkout refuses it (REQUIRED_MISSING) and nothing of it is kept, unless allow_missing. Then drive its stand with project: <its path> on every call.
- `worktree_ls`: Every checkout of this repository on this host: its slot (0 is the main checkout), project slug, branch, how many of its apps are online, its lease state and its path. A read only: a slot whose folder is gone shows (gone) as its branch until worktree_add or worktree_remove frees it. (read-only)
- `worktree_remove`: Stop and delete the apps of a worktree (freeing its leases), remove the checkout and free its slot; the branch stays. ref is its slot number, path or branch. A checkout with uncommitted or untracked changes is refused unless force, which discards them. The main checkout (slot 0) is never removed.
- `worktree_sync`: Bring an existing worktree of this repository the files a new one gets: the worktree: section's copy, required and link entries of its own manifest (else the main checkout's), plus the main checkout's override, copied from the main checkout. Files already there are kept. A missing required entry is refused unless allow_missing. Refused when the local host is readonly. No slot, override or install: worktree_add makes stands.
- `worktree_hook`: Install, remove or show mcproc's git post-checkout hook for this repository: once installed, every worktree made by any tool through git (Claude Code, Codex, a plain git worktree add) gets the worktree: files, and a missing required entry makes that git worktree add fail loudly. It lives in the repository's own git directory, never in a tracked file; another tool's post-checkout is never overwritten.

## FAQ

### How do I install mcproc?

You can install it globally using npm with `npm i -g mcproc` or run it directly using `npx -y mcproc`.

### Can mcproc manage processes on remote machines?

Yes, it works on the local machine and on remote hosts via SSH and docker exec.

### How does mcproc find the project manifest?

It searches for `.mcproc/mcproc.yaml` by checking the MCPROC_PROJECT environment variable, the CLAUDE_PROJECT_DIR, the client's MCP roots, and the current working directory, looking upward.
