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

Flag	Meaning
--stdio	Serve over stdin/stdout (default)
--http	Serve Streamable HTTP
--host <host>	HTTP bind host (default 127.0.0.1; implies HTTP)
--port <port>	HTTP bind port (default 3000; implies HTTP)
--cwd <dir>	Tool working directory
--readonly	Register only read-only tools
--tools <names>	Comma-separated subset
--shell <path>	Bash executable for bash
--allowed-hosts <h>	Comma-separated Host names for HTTP DNS-rebinding protection

--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	Role
read	Read a text file or image (offset / limit for large files)
bash	Run a shell command in --cwd
edit	Exact text replacement (same coercions as pi: JSON-string edits, single edit object, legacy oldText/newText)
write	Create/overwrite a file, creating parent directories
grep	Search file contents with rg
find	Glob files with fd
ls	List a directory

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.