pi-web-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pi-web-mcp Check my pi sessions and tell me what needs my attention"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pi-web-mcp
An MCP server for Pi Web — the web UI for the pi coding agent. It wraps Pi Web's HTTP API so any MCP client (pi, Claude Desktop, Cursor, your own agent…) can browse, triage, search, read and drive your pi sessions.
Pi Web itself only serves a browser. This server turns its API into 25 tools: list and filter sessions, read transcripts, triage which conversations are waiting for you, full-text search, send messages and wait for replies, fork/rename/delete sessions, inspect project diffs — over stdio or Streamable HTTP.
┌────────────┐ MCP (stdio / HTTP) ┌──────────────┐ HTTP ┌──────────┐
│ any AI │ ─────────────────────► │ pi-web-mcp │ ───────► │ pi-web │ ──► pi sessions
│ MCP client │ ◄───────────────────── │ (this repo) │ ◄─────── │ :30141 │ (~/.pi/agent/sessions)
└────────────┘ └──────────────┘ └──────────┘Quick start
Requires Node.js ≥ 22 and a running Pi Web instance.
# run it without cloning (npm resolves the GitHub repo)
npx -y github:glwhappen/pi-web-mcp --status # connectivity + config self-check
npx -y github:glwhappen/pi-web-mcp # stdio MCP server on stdin/stdoutOr install it once:
npm install -g github:glwhappen/pi-web-mcp # then run `pi-web-mcp`
# or, from a clone:
git clone https://github.com/glwhappen/pi-web-mcp && cd pi-web-mcp && npm ci
node src/index.js --statusConfigure the connection (either environment variables or ~/.config/pi-web-mcp/config.json):
export PI_WEB_URL=http://127.0.0.1:30141
export PI_WEB_PASSWORD=your-pi-web-password # Basic Auth, username is always `pi`Register it with your MCP client. For pi, ~/.pi/agent/mcp.json:
{
"mcpServers": {
"pi-web": {
"command": "npx",
"args": ["-y", "github:glwhappen/pi-web-mcp"],
"env": { "PI_WEB_URL": "http://127.0.0.1:30141", "PI_WEB_PASSWORD": "…" },
"exposure": "deferred",
"toolExposure": {
"piweb_triage": "direct",
"piweb_list_unread": "direct",
"piweb_list_sessions": "direct",
"piweb_get_session": "direct",
"piweb_search_sessions": "direct",
"piweb_send_message": "direct"
}
}
}
}For Claude Desktop / Cursor / any other client, use the same command + env shape (see HTTP mode for remote clients).
Related MCP server: Terminal Session Manager
Tools
Read
Tool | What it does |
| Connectivity + config self-check (address, password source, read/write mode, session count) |
| List/filter sessions: |
| Aggregate by project directory: sessions, running, unread, last activity |
| What needs attention: 🟠 awaiting input / 🔵 unread / 🟢 running |
| Classify every session: ❓ probably asking me / ⚠️ stopped mid-turn / 💤 stalled / 🟢 running / 💬 waiting for my next step — with the evidence for each verdict |
| Literal full-text search across all transcripts (server-side 3s budget, may truncate) |
| Read a transcript; |
| Global running snapshot, or one session's detail (streaming, queue, context usage) |
| Models available for a project, default model, thinking levels |
| List project files (git index first), fuzzy matched |
| Read a text file chunk (continue with |
| Changed files + insertions/deletions |
| Full patch for one file |
| Watch what a session is producing right now (event stream) |
Write
Tool | What it does |
| Send a prompt; with |
| Poll until the current turn finishes, return the last assistant reply |
| Create a session (optional first prompt, model, thinking level) |
| Copy the current branch into a new session |
| Let the model name a session |
| Switch a session's model |
| Stop the current turn |
| Update this server's read cursor (one/all, or mark unread again) |
| Rename a session |
| Export the session as pi's single-file HTML |
| Delete a session (needs |
The session argument accepts a full id, an id prefix, an exact name, or a fragment of the name/first message. An ambiguous match fails with the candidate list instead of guessing.
Triage rules
piweb_triage runs no model — it is pure rules over the last message on the active branch, whether a tool call is still pending, and how long the session has been quiet. Fast, cheap, reproducible, and every verdict carries its evidence.
Verdict | Evidence |
🟠 Awaiting input | Pi Web reports the session is blocked on an extension UI prompt |
🟢 Running | The session has a live agent process |
⚠️ Stopped mid-turn | Last entry is my message / a tool result / an unanswered tool call / an assistant message with no text |
💤 Stalled | Same as above, and the session has been idle for more than |
❓ Probably asking me | Last assistant message contains a question mark |
💬 Waiting for my next step | The assistant finished its turn |
⚪️ Empty | No messages (excluded by default) |
Read-cursor semantics
Pi Web keeps its "unread" markers in browser localStorage, which no server-side API exposes. This server therefore maintains its own cursor in <config dir>/read-state.json (the modified timestamp of each session you have read, guarded by a cross-process file lock). Reading a session via piweb_get_session / piweb_wait_for_reply updates it; piweb_mark_read manages it explicitly.
Browser unread and MCP unread are two different sets and do not affect each other.
Configuration
Command line > environment > ~/.config/pi-web-mcp/config.json > password files.
{
"baseUrl": "http://127.0.0.1:30141",
"username": "pi",
"password": "…",
"timeoutMs": 30000,
"httpToken": "…",
"writeRoots": [],
"tools": [],
"http": { "host": "127.0.0.1", "port": 30142 }
}Key / env var | Meaning |
| Pi Web address, default |
| Pi Web password (Basic Auth, username is always |
| Override the Basic Auth username |
| Password file; otherwise |
| Bearer token for HTTP mode. Required when binding a non-loopback host |
| Register read-only tools only (plus the local read cursor and |
| Array; when non-empty, write operations are only allowed for sessions inside these project roots |
| Array; when non-empty, only these tools are registered |
| HTTP mode listen address, default |
| Config directory, default |
CLI flags: --http, --host, --port, --http-token, --readonly, --write-root <dir> (repeatable), --tools a,b,c, --status, --version, --help.
HTTP mode (for remote AIs)
pi-web-mcp --http --host 172.17.0.1 --port 30142The endpoint is POST /mcp (Streamable HTTP, stateless: one server instance per request, so several clients can connect concurrently). Clients authenticate with Authorization: Bearer <httpToken> or X-Pi-Web-Mcp-Token.
Binding a non-loopback address without a token is refused at startup.
Client config for a remote endpoint:
{
"mcpServers": {
"pi-web": {
"url": "https://pi-mcp.example.com/mcp",
"headers": { "Authorization": "Bearer <httpToken>" }
}
}
}A systemd unit example lives in deploy/pi-web-mcp.service.example.
Security model
This server can start agents that edit files and run commands, so treat it as a privileged interface:
Never expose HTTP mode without a token. The server refuses to bind a non-loopback host without one.
--readonlyremoves every tool that changes state (16 tools remain in read-only mode vs 25 in read-write mode).--write-rootlimits write operations to sessions inside given project roots — useful when several agents share the endpoint.Put HTTPS in front (a reverse proxy such as nginx-proxy-manager) before exposing it to the internet.
Prefer stdio mode locally: nothing listens on a port, and the client controls the process lifetime.
piweb_delete_sessionrequires an explicitconfirm: true.
Development
git clone https://github.com/glwhappen/pi-web-mcp
cd pi-web-mcp
npm ci
npm test # unit tests against a mock pi-web (no real instance needed)
npm run smoke # read-only smoke test against a real pi-web
npm run smoke:write # write path end-to-end (creates a session — spends model tokens)Layout:
src/
index.js entry point: CLI flags, stdio/HTTP transports, graceful shutdown
client.js Pi Web HTTP client (Basic Auth, timeouts, retries, SSE subscription)
config.js config resolution (env > config.json > password files)
guard.js read/write boundaries (readonly, writeRoots)
session-index.js cached session list + id/name resolution
read-state.js read cursor (cross-process file lock)
triage.js session triage rules and rendering
format.js session/message → Markdown
tools/ {index,shared,read,write}.js — the 25 tools
test/
mock-piweb.mjs fake Pi Web server
server.test.mjs unit tests
deploy/
pi-web-mcp.service.exampleThe unit tests use a mock Pi Web, so they run anywhere — no pi installation required.
Limitations
Pi Web's unread markers are browser-local; this server keeps a separate cursor (see above).
piweb_search_sessionsis bounded by the server's 3-second search budget and can returntruncated.piweb_watch_sessionstarts the session's agent process if it is not running (the same thing opening the session in Pi Web does).piweb_send_messageandpiweb_create_sessionmake a real agent do real work — check the session before sending.HTTP mode is stateless: no server-initiated notifications, no SSE-only features.
License
MIT
Available Tools
25 toolspiweb_abort_session中断会话当前这一轮ADestructive
给正在运行的会话发 abort,停掉它当前这一轮(等价于界面上的 Stop)。
Inputs: session (required).
piweb_agent_state查看 agent 运行状态ARead-only
不带 session 时给全局快照(哪些会话在跑/等待输入);带 session 时给该会话的详细状态(是否流式中、上下文占用、模型、排队消息)。
Inputs: session.
piweb_auto_name_session让模型给会话起名AIdempotent
调用 pi 的标题生成,让模型根据对话内容给会话起一个名字并落盘(等价于侧边栏的自动命名)。要花一次模型调用。
Inputs: session (required).
piweb_create_session新建会话并可选发首条消息A
在指定项目目录下新建一个 pi 会话(返回真实 sessionId)。带 message 时把它作为首条提示词发出去;不带 message 时只创建运行时(ensure_session)。可选指定 provider/modelId/thinking_level,模型取值用 piweb_list_models 查。
Inputs: cwd (required), message, model_id, provider, +2 more.
piweb_delete_session删除会话ADestructive
删除会话(会连同它下面的子代理会话一起删掉,不可恢复)。必须显式传 confirm=true 才会执行。
Inputs: session (required), confirm.
piweb_export_session导出会话为 HTMLAIdempotent
把会话导出成 pi 官方单文件 HTML(可离线翻阅/分享),写到本地磁盘并返回路径。大会话导出要几秒。
Inputs: session (required), out_path.
piweb_fork_session从会话当前分支复制出新会话A
把会话当前分支整体复制成一个新会话(等价于侧边栏的 Fork)。原会话不受影响。用来「从这条线另开一条道」。
Inputs: session (required), name.
piweb_get_session读取会话内容A
读取一个会话的对话内容(默认最后 30 条消息,含工具调用摘要)。session 可传完整 id、id 前缀、会话名称或名称/首条消息片段。要读更早的历史用 offset 往前翻;思考内容默认只给预览,include_thinking="full" 会去取完整思考链。默认会把该会话在本地标记为已读。
Inputs: session (required), tail, format, offset, +5 more.
piweb_git_diff看单文件 git diffARead-only
看某个文件相对 git 的完整 patch。复制到会话里让 agent 改,或用来核查它的改动是否合理。
Inputs: cwd (required), path (required), max_chars.
piweb_git_status看项目 git 改动ARead-only
看某个项目目录的 git 状态:分支仓库根、改了哪些文件(状态码)、增删行数。用来验收 agent 到底动了什么。
Inputs: cwd (required).
piweb_list_files列项目文件ARead-only
列出某个项目目录下的文件(优先 git ls-files,跳过 .gitignore)。可带 filter 做模糊匹配。用来定位某个项目里有哪些文件可读。
Inputs: cwd (required), limit, filter.
piweb_list_models列出可用模型ARead-only
列出某个项目目录下 pi 可用的模型(provider/model 形式)与默认模型、可用思考等级。新建会话或切模型前拿它选值。
Inputs: cwd, limit, filter.
piweb_list_projects按项目聚合会话ARead-only
按项目目录聚合 pi-web 会话:每个目录有多少会话、几个在跑、几个未读、最近活动时间。用来先看「我的活儿都压在哪个目录」。
Inputs: limit, min_sessions.
piweb_list_sessions列出 pi-web 会话ARead-only
列出/筛选 pi-web 里的 pi 会话(按项目目录、关键词、状态、时间过滤)。status: all|running|awaiting|unread,unread 用的是本 MCP 自己的已读游标(与浏览器里的未读标记不共享)。keyword 只匹配会话名称/首条消息/目录,全文检索用 piweb_search_sessions,想要「哪些会话在等我」用 piweb_triage。
Inputs: cwd, sort, force, limit, +6 more.
piweb_list_unread未读/待介入的会话ARead-only
一次列出需要我关注的会话:🟠 正在等待用户输入的、🔵 本 MCP 上次读过之后又有新内容的、🟢 正在跑但我没看过的。注意:未读用的是本 MCP 的已读游标(用 piweb_get_session 或 piweb_mark_read 更新),与浏览器 localStorage 里的未读标记是两套。想按「对话结局」判断谁在等我,用 piweb_triage。
Inputs: cwd, limit, since.
piweb_mark_read标记会话已读/未读A
更新本 MCP 的已读游标:session 给了就标记该会话,省略则把当前所有未读会话一次性标记为已读;unread=true 则反过来清掉游标,让它重新算未读。只影响本 MCP 的游标,不碰浏览器里的未读标记。
Inputs: unread, session.
piweb_read_file读项目文件内容ARead-only
读一个文本文件的片段(服务端按块返回,默认一块;用 offset=nextOffset 继续读下一块)。只读文本类文件,二进制会被拒。
Inputs: path (required), offset, max_chars, session_id.
piweb_rename_session重命名会话BIdempotent
给会话改名字(等价于 pi-web 侧边栏的重命名)。
Inputs: name (required), session (required).
piweb_search_sessions全文搜索会话内容ARead-only
在所有会话的消息正文里做字面量(不区分大小写)搜索,返回命中片段所在的会话 id。服务端有 3 秒时间预算,结果可能被截断(truncated);命中很多时缩小关键词或用 piweb_get_session 细看。
Inputs: query (required), cwd, limit.
piweb_send_message给会话发消息A
向一个已有会话发送提示词(等价于在 pi-web 输入框里发消息),让它继续干活。会话没在运行时 pi-web 会自动把它拉起来。默认发完就返回;wait_seconds>0 时会等这一轮跑完并带回最后的助手回复。注意:这会让对方 agent 真正执行操作(改文件、跑命令),发之前确认会话选对了。
Inputs: message (required), session (required), wait_seconds, streaming_behavior.
piweb_set_model给会话换模型AIdempotent
切换某个会话接下来使用的模型(等价于界面上的模型选择)。会话没在运行时会被拉起来。取值先用 piweb_list_models 查。
Inputs: session (required), model_id (required), provider (required).
piweb_statuspi-web 连接自检ARead-only
检查 MCP 到 pi-web 的连接配置是否正常:地址、密码来源、会话总数、运行中的会话、读写边界(是否只读、允许写入的项目根)。连不上时先用这个排查。
Inputs: no named parameters.
piweb_triage会话分诊(谁在等我 / 谁半途死了)ARead-only
不经过模型,纯按「最后一条消息是谁 + 是否有悬挂的工具调用 + 多久没动」把会话分诊成:🟠等我回答(扩展弹窗)、❓可能在问我(最后一条助手消息带问号)、⚠️半途停下(最后一轮没有助手收尾)、💤停滞(半途停下且很久没动)、🟢在跑、💬等我下一步。每条都给判定依据,可复现、可核查。这是回答「现在还有多少对话在等我」最快的一招。默认只看最近 3 天有过活动的会话。
Inputs: cwd, limit, since, per_group, +3 more.
piweb_wait_for_reply等待会话这一轮结束并取回复A
轮询某个会话,等它这一轮跑完(不再流式输出),然后返回最后的助手回复文本。适合先 piweb_send_message 不等、之后再来收结果。
Inputs: session (required), max_chars, poll_seconds, timeout_seconds.
piweb_watch_session实时看会话正在输出什么A
订阅会话的事件流,在指定秒数内收集正在生成的内容(文本增量、思考增量、工具调用),返回期间累计的文本。适合「它现在跑到哪了」。注意:会话没在运行时订阅会把它拉起成一个空闲进程(等同在 pi-web 打开该会话)。
Inputs: session (required), seconds, until_idle, include_thinking.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target distinct verbs/resources, and descriptions explicitly cross-reference each other (e.g. list_unread vs triage vs list_sessions' unread filter). A few pairs still have fuzzy boundaries (watch_session vs wait_for_reply, list_unread vs triage), but the docs make the distinctions workable.
Every tool uses the same piweb_ prefix and a clean snake_case verb_noun pattern (list_sessions, get_session, delete_session, set_model). No convention mixing or vague names anywhere.
25 tools is on the heavy side for this surface. The domain is genuinely broad (sessions, messaging, files, git, models), but a few tools feel like they could merge, pushing it toward overload.
Strong lifecycle coverage: create/delete/fork/rename/export sessions, send/wait/watch messages, triage/unread/state inspection, model listing and switching, file and git inspection. Minor gaps like mutating thinking level or session config post-creation exist but are workable.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceExposes authorized ChatGPT, DeepSeek, Kimi, and Grok web sessions to agents as MCP tools, including chat and local file attachments over HTTP or stdio.7MIT
- FlicenseBqualityCmaintenanceEnables AI agents to create and control persistent terminal sessions, run and monitor asynchronous jobs, page through ordered event history, and resolve registered device connection details without exposing stored secrets. Exposes 15 MCP tools over stdio that mirror a REST API, keeping session state alive independently of the agent that started it.15-
- AlicenseNot gradedqualityBmaintenanceEnables unified access to multiple coding-agent CLIs via MCP, with tools for running prompts, managing sessions, and retrieving task outputs.MIT
- AlicenseNot gradedqualityCmaintenanceLets MCP clients create, resume, message, and stop Pi coding-agent sessions running on another machine, with conversations that survive client disconnects and server restarts. Sessions can be kept loopback-only or published privately to trusted callers over Tailscale HTTPS.1Apache 2.0