Pi MCP Bridge

Expose native Pi sessions through MCP, with owner-controlled permissions and one cooperating writer per session. Local clients use stdio; multiple or remote clients share a loopback HTTP service behind an authenticated tunnel.

What it does

• List authorized sessions, read recent turns in source order, search effective context and expand referenced messages or evidence.
• Read native Session Context, captured Runtime Context or explicitly enabled extension readers.
• Send text and images, run native shell commands, select model/thinking settings, compact context, reload idle sessions and stop work.
• Create or fork saved sessions, optionally sending a first task, and move deleted sessions to recoverable trash while retaining project files.
• Notify ChatGPT Work chats and dots when an owned RPC or connected TUI/RPC companion settles, with a short result excerpt and pinned native reading arguments.
• Batch independent operations and apply seven separate permissions at default, project and session tiers.

See working with a session for the dispatch, observation and continuation workflow, and the public API for tool arguments and outcomes.

Start locally

Requires Linux, Node.js 22.19 or later, and your own Pi installation (tested with Pi 1.4.0). Install and configure Pi first; Bridge uses that installation’s CLI, SDK and native authentication. Set piExecutable to an absolute Pi CLI path, or let the launch environment’s PATH select pi.

Get the source and prepare an owner configuration. Use absolute paths below, replacing the private directory with your chosen location:

command -v pi
pi --version
git clone https://github.com/XWIlluDelu/pi-mcp-bridge.git
cd pi-mcp-bridge
npm ci
mkdir -p -m 700 /absolute/private/path
cp deploy/owner.example.json /absolute/private/path/owner.json
chmod 600 /absolute/private/path/owner.json

Edit owner.json using configure one project: select the native session storage and project, then add its permission grant. The example denies all operations until you grant them. That guide also explains how storage paths differ from project paths and which directories must be private.

If the target session is already open in Pi, load its companion before remote control. Bridge can resume an inactive saved session itself. Use matching Bridge control components; live reads follow the independent read contract.

For one stdio MCP client:

{
  "command": "node",
  "args": ["/absolute/path/to/pi-mcp-bridge/src/server.mjs", "/absolute/private/path/owner.json"]
}

For multiple clients, start one HTTP service and use src/stdio-proxy.mjs for stdio-only clients. Transport setup covers tokens, tunnels and protocol versions.