pi-exec-mcp

An MCP server that runs pi coding-agent tasks in the background. An assistant dispatches a task, polls its status, reads the result, and cancels it if it is no longer needed — without pulling the delegate's context into its own.

This is a small, self-contained server. It contains no network code of its own: the delegate's model calls happen inside pi, using the provider, model, and key you have already configured in pi. There is no relay, no bundled endpoint, and no telemetry.

• English

• 中文

English

Tools

A task moves through starting → running → done | aborted | error. Judge liveness by state and turns, never by how much text has arrived: a reasoning model can be silent for a long time while it is still working.

Requirements

• Node.js >= 22.19.0.

• pi installed and authenticated by you, so it has a provider, a model, and a key in its own configuration. This server reads that configuration; it never supplies credentials.

• A working directory for each task that is an absolute path and is neither / nor your home directory.

Install

Cursor plugin. Clone or install this repository as a plugin and the bundled mcp.json runs the server out of the plugin folder itself:

{
  "mcpServers": {
    "pi-exec": {
      "type": "stdio",
      "command": "node",
      "args": ["${CURSOR_PLUGIN_ROOT}/dist/index.js"]
    }
  }
}

${CURSOR_PLUGIN_ROOT} is the folder the plugin was installed into. No npm install and no npx are involved: dist/ is committed with every dependency bundled into it, so the only thing the plugin needs is the Node.js from the requirements above (>= 22.19.0).

dist/ is generated by npm run build — tsc for the type declarations, esbuild for the self-contained server — so rebuild it after touching src/.

npm. Not published yet, so there is nothing to install today. Once it is, the same server is available as:

npm install -g pi-exec-mcp

Configure your MCP client

Any stdio client works: point it at the dist/index.js in the plugin folder as above, or at the published package once there is one. Set any environment variables below in the server's env block, not in a shell profile: MCP hosts often launch servers with a stripped environment.

Environment variables

Safety notes

• This is not a sandbox. pi has no permission system. A delegate granted bash can do anything the user running this server can do. The default tool set is read-only (read, grep, find, ls), and anything wider is opt-in per task or via PI_EXEC_ALLOW_TOOLS / PI_EXEC_ALLOW_WRITE.

• The working directory is enforced. Each task must name an absolute, existing directory that is not / and not the home directory. Relative paths are refused rather than resolved against the server's own working directory.

• Credential paths are blocked. A guard installed on every session refuses tool calls that target .env* files, .ssh, .aws, .gnupg, .docker, .kube, auth.json, and similar locations, including through symlinks.

• No secrets are stored or relayed. The provider, model, and key come from your pi configuration. This server adds no endpoints, no proxy, and no telemetry.

• Resource limits are advisory guards, not guarantees. The memory floor and concurrency ceiling prevent obvious overcommitment; they do not make a task safe to run.

Attribution

This project is based on and derived from two MIT-licensed works:

• howznguyen/pi-delegate-mcp — the base server, worker, and tool architecture.

• Nyarlathoteppppp/pi-durabletask-mcp — the working-directory and credential-path guards (src/workspace.ts, src/secrets.ts).

Both are used and redistributed under the MIT License. See LICENSE for the original copyright notices.

License

MIT. See LICENSE.

Related MCP server: pi-delegate

中文

一个 MCP 服务器，把 pi 编码智能体的任务放到后台运行。 助手可以派发任务、轮询状态、读取结果，并在不再需要时取消它，而不会把被委派者的上下文 带进自己的对话。

这是一个小巧、自包含的服务器。它自身没有任何网络代码：被委派者的模型调用发生在 pi 内部，使用你已经在 pi 里配置好的服务商、模型和密钥。没有中转，没有内置端点，也没有遥测。

工具

任务的状态流转为 starting → running → done | aborted | error。判断存活要看 state 和 turns，不要看已经产出多少文本：推理模型可能长时间没有输出，但它仍在工作。

环境要求

• Node.js >= 22.19.0。

• 你已经安装并登录 pi，它自己的配置里已有服务商、模型和密钥。本服务器只读取该 配置，绝不提供凭据。

• 每个任务的工作目录必须是绝对路径，且不能是 /，也不能是主目录。

安装

Cursor 插件。 把本仓库作为插件克隆或安装后，仓库自带的 mcp.json 会直接 在插件目录里启动本服务器：

{
  "mcpServers": {
    "pi-exec": {
      "type": "stdio",
      "command": "node",
      "args": ["${CURSOR_PLUGIN_ROOT}/dist/index.js"]
    }
  }
}

${CURSOR_PLUGIN_ROOT} 是插件被安装到的目录。全程不需要 npm install，也不需要 npx： dist/ 已随仓库提交，并且把全部依赖都打包了进去，插件唯一需要的就是上面「环境要求」中的 Node.js（>= 22.19.0）。

dist/ 由 npm run build 生成 —— tsc 产出类型声明，esbuild 产出自包含的服务器 —— 修改 src/ 后请重新构建。

npm。 目前尚未发布到 npm，因此暂时无可安装的内容。发布之后，同一个服务器也可以这样运行：

npm install -g pi-exec-mcp

配置 MCP 客户端

任何 stdio 客户端都可以：像上面那样指向插件目录里的 dist/index.js；等 npm 发布后也可以 指向 npm 包。下面这些环境变量请写在服务器的 env 块里，而不是 shell 配置里：MCP 宿主启动 服务器时常常会清空环境变量。

环境变量

安全说明

• 这不是沙箱。 pi 没有权限系统。被授予 bash 的任务能做运行本服务器的用户能做的 任何事。默认工具集是只读的（read、grep、find、ls），更宽的权限需要按任务显式 开启，或通过 PI_EXEC_ALLOW_TOOLS / PI_EXEC_ALLOW_WRITE 打开。

• 强制校验工作目录。 每个任务必须指定一个绝对且存在的目录，且不能是 /，也不能是 主目录。相对路径会被直接拒绝，而不会回退到服务器自身的工作目录。

• 凭据路径被拦截。 每个会话都会安装一个守卫，拒绝访问 .env* 文件、.ssh、.aws、 .gnupg、.docker、.kube、auth.json 等位置，包括通过符号链接的访问。

• 不保存、不中转任何密钥。 服务商、模型和密钥都来自你的 pi 配置。本服务器不新增任何 端点、代理或遥测。

• 资源限制是提示性护栏，不是保证。 内存下限和并发上限能避免明显的资源超用，但不会让 任务本身变得安全。

致谢

本项目基于以下两个 MIT 许可的作品衍生而来：

• howznguyen/pi-delegate-mcp —— 基础 服务器、worker 与工具架构。

• Nyarlathoteppppp/pi-durabletask-mcp —— 工作目录守卫与凭据路径守卫（src/workspace.ts、src/secrets.ts）。

二者均在 MIT 许可下使用与再分发。原始版权声明见 LICENSE。

许可证

MIT，见 LICENSE。