pi-mcp

MCP server that exposes pi coding-agent tools:

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

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

Requirements

• Deno >= 2.9

• rg and fd on PATH (used by grep / find; never downloaded by pi-mcp)

Install

From a checkout:

deno install -g -A -n pi-mcp --config deno.json ./src/cli.ts

Passing --config deno.json makes the installed command use this project's Deno configuration instead of relying on auto-discovery during installation.

By default, Deno installs the launcher under ~/.deno/bin. If that directory is not on your PATH, you can either add it or choose a different installation root.

For example, to install pi-mcp as ~/.local/bin/pi-mcp:

deno install -g -A -n pi-mcp --config deno.json --root "$HOME/.local" ./src/cli.ts

Deno places global executables in the bin subdirectory of the installation root, so --root "$HOME/.local" means ~/.local/bin.

You can also set DENO_INSTALL_ROOT instead of passing --root each time:

export DENO_INSTALL_ROOT="$HOME/.local"
deno install -g -A -n pi-mcp --config deno.json ./src/cli.ts

-A is intentional: the exposed tools can read/write files and execute commands, so the server needs the same broad local permissions as the tools it exposes.

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

Tool execution behavior is taken from pi's coding-agent tools, including image normalization/resizing. TUI rendering is not included. One deliberate difference is rg / fd discovery: pi-mcp only uses executables already present on PATH and never downloads them automatically.

The vendored tool/helper code in this checkout is based on pi commit 59a71b235dadb4ad0d67557a8abb0aaa093e68b4.

Development

deno install
deno task check
deno task start --help

Useful tasks: deno task dev, deno task check, deno task lint, and deno task fmt.

Runtime dependencies: @modelcontextprotocol/server, @silvia-odwyer/photon-node, zod, diff.