pi-mcp

MCP server that exposes pi coding-agent tools:

read, bash, edit, write, grep, find, ls

Built with Bun and @modelcontextprotocol/server v2. Serves both the 2026-07-28 era (server/discover) and 2025-era initialize.

Requirements

• Bun >= 1.2

• rg and fd on PATH (used by grep / find; not downloaded)

Install

Use an absolute path. Do not pass . — Bun's global installer can write a duplicate pi-mcp key and an empty "": "." entry into ~/.bun/install/global/package.json / bun.lock (oven-sh/bun#19559, oven-sh/bun#24207).

bun add -g /absolute/path/to/pi-mcp
# same thing from the checkout:
bun add -g "$(pwd)"

bun install -g is an alias of bun add -g; the path is what matters. The binary lands on PATH as pi-mcp (~/.bun/bin).

For local development, bun link in this directory instead.

Usage

pi-mcp                         # stdio (default)
pi-mcp --http --port 3000      # Streamable HTTP
pi-mcp --cwd /path/to/project
pi-mcp --readonly              # read, grep, find, ls
pi-mcp --tools read,grep,ls
pi-mcp --shell /bin/bash

--stdio cannot be combined with --http / --host / --port.

Log to stderr. stdout is the stdio protocol channel.

Host config (stdio)

{
  "mcpServers": {
    "pi": {
      "command": "pi-mcp",
      "args": ["--cwd", "/path/to/project"]
    }
  }
}

HTTP

pi-mcp --http --host 127.0.0.1 --port 3000

POST JSON-RPC to the listener. Modern (2026-07-28) clients use server/discover plus the per-request _meta envelope and Mcp-Method / MCP-Protocol-Version headers. 2025 clients use initialize.

Tools

Execute behavior is taken from pi's coding-agent tools. TUI rendering, photon image resizing, and automatic rg/fd downloads are not included.

Development

bun install
bun src/cli.ts --help

Runtime dependencies: @modelcontextprotocol/server, zod, diff.