Allows coding agents to control PM2 processes across local, SSH, and Docker hosts using a project-based manifest.
Also known as kiwagu/mcproc
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is mcproc MCP?
mcproc allows coding agents to control PM2 processes across local, SSH, and Docker hosts using a project-based manifest. It exposes 4 tools, such as logs, init, unpack.
Summary generated from the project's README
About mcproc MCP server
Managing application lifecycles and monitoring processes across multiple environments is what mcproc enables for coding agents. By using a project-based YAML manifest, an AI client can orchestrate PM2 processes on a local machine, over SSH connections, or inside Docker containers. This allows an agent to manage complex setups where different services reside on different hosts while maintaining a unified view of the entire project.
Developers use this server to automate the starting, restarting, and stopping of specific application profiles or individual services. The server provides tools to inspect process status, check memory and CPU usage, and verify that applications are listening on their declared ports. It also handles dependency management, ensuring that build tasks or library compilations complete before a server starts. Because it integrates with PM2, any changes made by the agent are immediately visible in standard terminal monitoring tools.
What you can do with it
- 1Debug application errorsA developer can ask an AI to find recent crashes or error patterns in specific service logs.
- 2Verify network configurationsAn agent can check if a running application is actually listening on the expected network port.
Written from the project's README. Every use case is checked against a quote from it.
How to install mcproc MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall mcproc MCP in Claude Code
$ claude mcp add mcproc -- npx -y mcprocInstall mcproc MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcproc": {
"command": "npx",
"args": [
"-y",
"mcproc"
]
}
}
}Install mcproc MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcproc": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcproc"
]
}
}
}Install mcproc MCP in VS Code CLI
$ code --add-mcp '{"name":"mcproc","type":"stdio","command":"npx","args":["-y","mcproc"]}'Install mcproc MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcproc": {
"command": "npx",
"args": [
"-y",
"mcproc"
]
}
}
}Install mcproc MCP in Codex
$ codex mcp add mcproc -- npx -y mcprocInstall mcproc MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcproc] command = "npx" args = ["-y", "mcproc"]
Install mcproc MCP in Gemini CLI
$ gemini mcp add -s user mcproc npx -- -y mcprocInstall mcproc MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcproc": {
"command": "npx",
"args": [
"-y",
"mcproc"
]
}
}
}mcproc MCP tools 4
Detected from the READMElogsinitunpackstacks
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablekiwagu/mcproc is public and reachablegithub.com/kiwagu/mcproc ↗Pass
- Package names this repository as its sourcemcproc names kiwagu/mcproc as sourcenpmjs.com/package/mcproc ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for mcprocnpmjs.com/package/mcproc/v/0.19.2#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/kiwagu/mcproc ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcprocPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcproc
pm2 process control for coding agents, over MCP and on the command line. One manifest per project
describes what each launch is; the agent (or you) starts, restarts, reads logs and, above all, sees
which ports each app really listens on. Works on the local machine and on remote hosts over ssh
and docker exec. The processes are plain pm2 processes: pm2 monit in any shell shows the same thing.
Install and register
npm i -g mcproc # or run it with: npx -y mcproc
claude mcp add -s user mcproc -- mcproc mcp # Claude Code, once, user scope
From a checkout instead: bun run build && node dist/cli.js install writes a mcproc launcher into
~/.local/bin (adding that directory to your shell rc when it is not on PATH yet); install --uninstall removes it.
Codex (~/.codex/config.toml):
[mcp_servers.mcproc]
command = "mcproc"
args = ["mcp"]
The server finds the project from MCPROC_PROJECT, then CLAUDE_PROJECT_DIR (set by Claude Code),
then the client's MCP roots, then its working directory, and looks upward for .mcproc/mcproc.yaml.
Every tool also accepts an explicit project path.
Quick start
cd my-project
mcproc init # writes .mcproc/ (gitignored) with a manifest draft: on a turbo repo the dev task's apps are live, the rest commented out
$EDITOR .mcproc/mcproc.yaml # write a description for each app; uncomment what else you need
mcproc start base # or an app name, or "all"
mcproc ls # status, pid, uptime and real vs declared ports
mcproc init --adopt-ports # write the ports ls shows as undeclared into the manifest
mcproc logs api -n 200
mcproc logs base --since 2m # every app of a profile, merged by time stamp
mcproc doctor # why a host cannot be driven, and what to do
The manifest: .mcproc/mcproc.yaml
version: 1
project: demo # pm2 namespace and process-name prefix; default: directory name
vars: # per-checkout values (docs/variables.md)
slot: 0
apps:
libs:
description: one-shot build of the shared libraries into dist/
kind: task # runs once; ls shows done / failed (exit N)
run: npm run build:libs
api-build:
description: tsc watch build of the API into dist/
kind: build # build | server | worker | task (default server)
run: npx tsc -w -p apps/api
api:
description: HTTP API serving /health
run: node dist/apps/api/main.js
cwd: . # relative to the project root
env: { PORT: 3310 }
port: 3310 # declared listening port (or ports: [3310, 9230])
url: http://localhost:3310/ # the address to open; ls/describe show it with the HTTP answer (docs/urls.md)
memory: 600M # expected memory (docs/memory.md)
containers: [demo-db] # docker containers the app owns
watch: [dist/apps/api] # pm2 restarts the server when the build output changes
depends_on:
- { app: libs, condition: completed } # wait for the build to exit 0
- api-build # plain name = started (start order only)
profiles:
base: [libs, api-build, api] # "all" is built in
hosts: # "local" is implicit
stand:
ssh: stand # alias from ~/.ssh/config; no secrets live here
cwd: /srv/demo # project root on that host
prod:
ssh: prod
docker: { container: demo-app, user: node }
cwd: /home/node/demo
readonly: true # every mutating tool is refused here
The folder is created with a .gitignore containing *: it never enters your repository, so each
checkout keeps its own. .mcproc/README.md holds free-form notes that describe returns. The remaining
fields, the kinds and the process naming: the manifest.
Tools (MCP) and commands (CLI)
| tool (CLI form when it differs) | what it does |
|---|---|
describe [app] |
the project summary (apps with descriptions, profiles, hosts, the notes file), or one app in detail |
ls [app] |
one row per app from the host it runs on: status, pid, uptime, restarts, memory and CPU of the process tree, ports with ✓/✗ against the declared ones, the URL's answer; reloads adds the in-process reloads since the pm2 start |
ports [port] |
every listening socket on the host with its pid and owning app, or who holds one port |
logs |
one app's tail, or several apps merged by time: the latest lines, since a span or a time, or last (logs) |
incidents [app] |
new errors with context since they were last taken, plus crashes and restarts; peek looks without taking (incidents) |
wait <app> with until (CLI --until) |
block until listening, url-ok, exited, a log line matches, idle, or reloaded (readiness) |
start, restart, stop, delete <target> |
by app or profile; start launches dependencies first and waits for their conditions, reload restarts the apps already online, and a stand the host cannot hold yet is queued (memory) |
flush [app] |
truncate the pm2 log files; incidents start over from there |
init |
a manifest draft from the repository's scripts and workspaces; adopt_ports writes the ports ls reports as undeclared into the existing manifest (init) |
hosts, doctor |
the hosts and the apps bound to each; per-host readiness, which pm2 a host would use and why, where each url answers (hosts) |
unpack |
bring pm2, and Node when the host has none, to a host (hosts) |
leases, lease_cancel (CLI leases cancel <id>) |
this machine's memory lease queue; cancel a pending lease (memory) |
stacks |
every mcproc stack on this machine, not only this project: the checkouts any mcproc call has seen and those found in the local pm2, with their hosts, apps, memory and ports, plus pm2 processes no manifest knows; all adds the recorded ones with nothing running (monit) |
exec -- <command> |
a one-off command from the project root with the manifest's exec.env, under a lease with --memory; one run at a time per --exclusive <group> |
worktree_add, worktree_ls, worktree_remove, worktree_sync, worktree_hook (CLI worktree add | ls | remove | sync | hook) |
an isolated checkout per branch with its own slot, slug and ports; required files refuse a worktree without them, and a git hook gives worktrees made by other tools the same files (worktrees) |
Every tool takes project; the tools that act on apps take host too, and without it each app is reached where it
runs (hosts). Leases, exec and worktrees are local to this machine. Read-only tools are annotated as such; mutating tools refuse readonly hosts and unknown app names before touching
any host. mcproc monit is the terminal dashboard on the same data; outside a project, or with --all, it lists every stack of the machine (monit). Text tables fit the terminal's width, wrapping long cells inside their column.
Documentation
- The manifest: every field, the kinds, process names
init: how the draft is made, turbo monorepos, adopting ports- Hosts: apps on several hosts, what a host needs, how ports are found,
unpack - Variables: per-checkout values and the override file
- Worktrees: one checkout per branch, each with its own slot
- Memory: budgets, the lease queue,
exec - Readiness:
waitanddepends_onconditions - Logs: since a point in time, live following, colors
- Incidents: new errors, what counts as one, per-app patterns
- Reloads: the in-process reloads of watchers, and where they show
- URLs: where a url is checked from and what the answer means
- monit: the dashboard and its keys
License
MIT, see LICENSE.
mcproc MCP questions
How do I add mcproc MCP to Claude Code?
Run claude mcp add mcproc -- npx -y mcproc in your terminal. Add --scope user to make it available in every project.
How do I add mcproc MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does mcproc MCP provide?
It exposes 4 tools, including logs, init, unpack, stacks.
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.