Skip to main content
Glama

pi-web-mcp

English | 简体中文

test

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/stdout

Or 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 --status

Configure 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

piweb_status

Connectivity + config self-check (address, password source, read/write mode, session count)

piweb_list_sessions

List/filter sessions: cwd, project, keyword, status, since, sort, limit

piweb_list_projects

Aggregate by project directory: sessions, running, unread, last activity

piweb_list_unread

What needs attention: 🟠 awaiting input / 🔵 unread / 🟢 running

piweb_triage

Classify every session: ❓ probably asking me / ⚠️ stopped mid-turn / 💤 stalled / 🟢 running / 💬 waiting for my next step — with the evidence for each verdict

piweb_search_sessions

Literal full-text search across all transcripts (server-side 3s budget, may truncate)

piweb_get_session

Read a transcript; offset pages backwards, include_thinking=none/preview/full

piweb_agent_state

Global running snapshot, or one session's detail (streaming, queue, context usage)

piweb_list_models

Models available for a project, default model, thinking levels

piweb_list_files

List project files (git index first), fuzzy matched

piweb_read_file

Read a text file chunk (continue with offset)

piweb_git_status

Changed files + insertions/deletions

piweb_git_diff

Full patch for one file

piweb_watch_session

Watch what a session is producing right now (event stream)

Write

Tool

What it does

piweb_send_message

Send a prompt; with wait_seconds > 0, wait for the turn and return the reply

piweb_wait_for_reply

Poll until the current turn finishes, return the last assistant reply

piweb_create_session

Create a session (optional first prompt, model, thinking level)

piweb_fork_session

Copy the current branch into a new session

piweb_auto_name_session

Let the model name a session

piweb_set_model

Switch a session's model

piweb_abort_session

Stop the current turn

piweb_mark_read

Update this server's read cursor (one/all, or mark unread again)

piweb_rename_session

Rename a session

piweb_export_session

Export the session as pi's single-file HTML

piweb_delete_session

Delete a session (needs confirm=true; subagent sessions go with it)

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 stalled_hours (default 6)

❓ 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

baseUrl / PI_WEB_URL

Pi Web address, default http://127.0.0.1:30141

password / PI_WEB_PASSWORD

Pi Web password (Basic Auth, username is always pi)

PI_WEB_USERNAME

Override the Basic Auth username

PI_WEB_PASSWORD_FILE

Password file; otherwise ~/.config/pi-web-mcp/password, then ~/pi-web.password

httpToken / PI_WEB_MCP_TOKEN

Bearer token for HTTP mode. Required when binding a non-loopback host

readonly / PI_WEB_MCP_READONLY=1

Register read-only tools only (plus the local read cursor and wait_for_reply)

writeRoots

Array; when non-empty, write operations are only allowed for sessions inside these project roots

tools

Array; when non-empty, only these tools are registered

http.host / http.port

HTTP mode listen address, default 127.0.0.1:30142

PI_WEB_MCP_HOME

Config directory, default ~/.config/pi-web-mcp

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 30142

The 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.

  • --readonly removes every tool that changes state (16 tools remain in read-only mode vs 25 in read-write mode).

  • --write-root limits 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_session requires an explicit confirm: 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.example

The 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_sessions is bounded by the server's 3-second search budget and can return truncated.

  • piweb_watch_session starts the session's agent process if it is not running (the same thing opening the session in Pi Web does).

  • piweb_send_message and piweb_create_session make 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 tools
piweb_abort_session中断会话当前这一轮A
Destructive

给正在运行的会话发 abort,停掉它当前这一轮(等价于界面上的 Stop)。

Inputs: session (required).

piweb_agent_state查看 agent 运行状态A
Read-only

不带 session 时给全局快照(哪些会话在跑/等待输入);带 session 时给该会话的详细状态(是否流式中、上下文占用、模型、排队消息)。

Inputs: session.

piweb_auto_name_session让模型给会话起名A
Idempotent

调用 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删除会话A
Destructive

删除会话(会连同它下面的子代理会话一起删掉,不可恢复)。必须显式传 confirm=true 才会执行。

Inputs: session (required), confirm.

piweb_export_session导出会话为 HTMLA
Idempotent

把会话导出成 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 diffA
Read-only

看某个文件相对 git 的完整 patch。复制到会话里让 agent 改,或用来核查它的改动是否合理。

Inputs: cwd (required), path (required), max_chars.

piweb_git_status看项目 git 改动A
Read-only

看某个项目目录的 git 状态:分支仓库根、改了哪些文件(状态码)、增删行数。用来验收 agent 到底动了什么。

Inputs: cwd (required).

piweb_list_files列项目文件A
Read-only

列出某个项目目录下的文件(优先 git ls-files,跳过 .gitignore)。可带 filter 做模糊匹配。用来定位某个项目里有哪些文件可读。

Inputs: cwd (required), limit, filter.

piweb_list_models列出可用模型A
Read-only

列出某个项目目录下 pi 可用的模型(provider/model 形式)与默认模型、可用思考等级。新建会话或切模型前拿它选值。

Inputs: cwd, limit, filter.

piweb_list_projects按项目聚合会话A
Read-only

按项目目录聚合 pi-web 会话:每个目录有多少会话、几个在跑、几个未读、最近活动时间。用来先看「我的活儿都压在哪个目录」。

Inputs: limit, min_sessions.

piweb_list_sessions列出 pi-web 会话A
Read-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未读/待介入的会话A
Read-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读项目文件内容A
Read-only

读一个文本文件的片段(服务端按块返回,默认一块;用 offset=nextOffset 继续读下一块)。只读文本类文件,二进制会被拒。

Inputs: path (required), offset, max_chars, session_id.

piweb_rename_session重命名会话B
Idempotent

给会话改名字(等价于 pi-web 侧边栏的重命名)。

Inputs: name (required), session (required).

piweb_search_sessions全文搜索会话内容A
Read-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给会话换模型A
Idempotent

切换某个会话接下来使用的模型(等价于界面上的模型选择)。会话没在运行时会被拉起来。取值先用 piweb_list_models 查。

Inputs: session (required), model_id (required), provider (required).

piweb_statuspi-web 连接自检A
Read-only

检查 MCP 到 pi-web 的连接配置是否正常:地址、密码来源、会话总数、运行中的会话、读写边界(是否只读、允许写入的项目根)。连不上时先用这个排查。

Inputs: no named parameters.

piweb_triage会话分诊(谁在等我 / 谁半途死了)A
Read-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

    A3.8/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes authorized ChatGPT, DeepSeek, Kimi, and Grok web sessions to agents as MCP tools, including chat and local file attachments over HTTP or stdio.
      7
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables unified access to multiple coding-agent CLIs via MCP, with tools for running prompts, managing sessions, and retrieving task outputs.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets 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.
      1
      Apache 2.0