Writ Cloud

---

writ-mcp 将 stdio MCP 客户端 — Claude Code、Claude Desktop、Cursor、 Windsurf、Codex — 连接到 Writ，让你已经录制的浏览器 工作流变成助手可调用的工具：运行工作流、读取收集的数据、搜索过往结果、安排任务、 将其公开为 REST 端点，以及启动网站抓取。

它只是一个透明的 stdio↔HTTP 代理。所有工具、架构和规则都位于 服务端，因此你获得的功能始终与实例支持的功能一致，而且新增工具无需升级此软件包。 零依赖、单文件，仅使用 Node 核心模块。

原生支持 Streamable HTTP 的客户端完全不需要它 — 直接将它们指向 /mcp 端点， 并添加 Authorization: Bearer <key> 标头即可。

快速开始

1. 获取 API 密钥。 在 Writ 应用中：Settings → Developers → API keys。密钥 格式类似 wt_…。

2. 添加服务。

连接到可自托管的协调器：

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://writ.example.com

连接到此计算机上的协调器：

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url http://localhost:8000

连接到已发布的单工作流端点（“Expose as MCP” slug URL 将按原样使用 — 不会重写路径）：

claude mcp add my-tools -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://mcp.example.com/mcp/my-tools

3. 检查连接。

claude mcp list

未传入 --url 时，默认目标为 Writ Cloud （https://api.usewrit.app）。传入 --url 可将连接器指向你自己的 协调器。请参阅状态。

通过环境变量传递密钥，而不是通过命令行。 --api-key 虽然可用，但会将密钥放入进程的参数列表，任何本地进程都可以通过 ps 读取， 而且 shell 会将其记录在历史记录中。使用此参数时，连接器会打印提示。

正在运行的协调器也会在其连接页面和 GET /api/mcp/connect-info 中提供预填好信息的单行命令：

Claude Desktop / Cursor（配置文件）

将配置添加到 claude_desktop_config.json（Claude Desktop）或 ~/.cursor/mcp.json （Cursor）中。建议使用 env 形式 — 它可以避免将密钥放入参数列表：

{
  "mcpServers": {
    "writ-selfhost": {
      "command": "npx",
      "args": ["-y", "writ-mcp"],
      "env": {
        "WRIT_COORDINATOR_URL": "https://writ.example.com",
        "WRIT_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

不使用 npm

自托管安装会将此连接器打包在 connectors/writ-mcp 中。无需构建步骤， 因此你可以直接从磁盘运行：

node /path/to/writ/connectors/writ-mcp/index.js --url https://writ.example.com

它可以与其他 Writ 服务共存。 每个界面都按设计使用各自的 slug 注册——桌面应用为 writ，Writ Cloud 为 writ-cloud，自托管协调器为 writ-selfhost——并且每个界面都会以不同的标题向助手标识自己。你可以同时连接任意组合。

可用工具

工具由你连接的服务提供，而非此软件包提供，因此服务新增工具后，你无需更新连接器即可使用。Writ Cloud 列出了以下 39 个工具；自托管协调器会列出其列中标记的工具。

工具	功能	Writ Cloud	自托管
writ_list_workflows	查看已保存的工作流（只有固定的工作流才会添加 run_<name> 工具）	是	是
writ_run_workflow	运行一个工作流并等待提取的数据	是	是
writ_pin_workflow_tool	将工作流固定或取消固定为独立的 run_<name> 工具——默认关闭，数量有限；所有工作流仍可通过 writ_run_workflow 运行	是	是
writ_update_workflow	查看工作流大纲，或直接编辑工作流（设置、步骤、函数及其 Agent 技能）	是	是
writ_diagnose_http_workflow	查看某次运行的每个请求收到的响应，以及运行时是否未使用浏览器	是	否
writ_create_http_extraction	根据捕获的请求创建无浏览器的多请求提取流程	是	否
writ_workflow_data	查看工作流累积的数据表	是	是
writ_search_data	搜索已收集的所有内容	是	是
writ_export_data	将工作流数据导出为 CSV/JSON	是	是
writ_workflow_runs	查看运行历史和状态	是	是
writ_set_schedule	为工作流安排计划（按间隔、每天或每周）	是	是
writ_expose_workflow_api	将工作流发布为可调用的 REST 端点	是	是
writ_scrape	将一个或多个页面读取为简洁的 Markdown（Cloud 还可以读取列表页面的前 N 项）	是	是
writ_crawl_site / writ_crawl_status	启动并查询分布式网站爬取任务	是	是
writ_crawl_files	查看爬取时捕获的原始文档（PDF、Office 文件、图片）	是	否
writ_saved_crawls / writ_run_saved_crawl / writ_saved_crawl_data	查看已保存的爬取任务（见下文）	是	是
writ_update_saved_crawl	检查或更改已保存爬取任务的设置	是	否
writ_personas	查看已保存的登录身份并准备好使用（见下文）	是	是
writ_payment	使用用户批准的银行卡付款；用户确认后，Writ 才会下单	是	否
writ_devices	查看关联的 Writ 桌面端：列出设备，或将此连接指向某台设备	是	否
writ_create_automation	事件或定时触发 → 运行工作流、发送通知或唤醒 Agent	是	是
writ_list_webhooks	查看入站 webhook URL 及其触发的自动化	是	是
writ_create_monitor / writ_wire_monitor	监控页面并对变化作出响应	是	是
writ_browser_use	打开由助手逐步操控的真实浏览器	是	是
writ_record_website	将可重复执行的任务记录为工作流	是	是
writ_website_to_api	将网站转换为可调用的 API	是	是
writ_discovery_status	跟进 API 构建进度，直至完成	是	否
writ_browser_act / _context / _network / _save / _cancel	在浏览器中执行操作，读取页面及其网络请求，并保存或关闭会话	是	是
writ_browser_compose	在会话中定义命名函数、输入和明确的步骤	是	否
writ_browser_ask_user	在实时浏览器中将 CAPTCHA、验证码或决策交由用户处理	是	否
writ_browser_sessions	查看可恢复的已打开浏览器会话	是	否
writ_record_start / _act / _context / _network / _save / _cancel	浏览器操作循环的旧名称，保留以兼容旧版	否	是

构建工具（writ_browser_use、writ_record_website、writ_website_to_api，以及 writ_browser_act / _context / _network / _save / _cancel）在两种目标环境中都可用； 两者都没有 writ_build 工具，因此请使用 writ_record_website。你的 助手会打开真实浏览器，逐步操控浏览器，并将会话保存为可重复使用的工作流； 此后重放工作流时，无需大模型参与。Writ Cloud 会在 Writ 的集群上运行该工作流； 自托管协调器则会在你自己的 集群 Agent 上运行。无论哪种方式，助手都是核心——无需使用第二个模型密钥。

重用最近的结果（max_age）

运行工作流会驱动真实浏览器，因此在同一会话中重复提问两次，就要完整运行两次并等待两次。每个工作流工具都接受一个可选的 max_age（秒），表示近期的答案就足够了：

{ "name": "run_price_check", "arguments": { "sku": "B0C123", "max_age": 300 } }

• 省略或设为 0 — 始终重新运行（默认值；结果不会自行过期）。
• N — 若结果的时间不到 N 秒，则重用；否则重新运行。

重用的答案会带有 _cache: {hit: true, age_seconds: N}，以便助手判断结果有多新。

max_age 对 Writ Cloud 和可自托管协调器的作用完全相同，也适用于固定工作流自身的 run_<name> 工具和 writ_run_workflow。

调用已保存的爬取（writ_run_saved_crawl）

整站爬取速度慢且按量计费，因此为了回答同一个问题而重新爬取，是助手可能犯下的代价最高的错误。已保存的爬取是一个以稳定名称保存的爬取配置，同样适用 max_age 规则：

{ "name": "writ_run_saved_crawl", "arguments": { "crawl": "docs", "max_age": 86400 } }

• 命中 — 该爬取已收集的页面会立即以内联形式返回，不会执行爬取，也不会产生费用。
• 未命中 — 使用已保存的设置重新爬取网站，并返回一个可通过 writ_crawl_status 轮询的爬取 ID（一次爬取的生命周期可能超过单次工具调用）。

以下三个工具涵盖了相关操作：

工具	功能
writ_saved_crawls	列出已保存的爬取。再次爬取网站前，请先在这里检查。
writ_run_saved_crawl	运行一个已保存的爬取，并在 max_age 允许时重用近期数据。
writ_saved_crawl_data	读取某个爬取已收集的内容，不限时效。绝不会执行爬取。

要创建已保存的爬取，请向 writ_crawl_site 传入 save_as——这会保存设置并运行爬取，因此也可以通过 REST 调用该爬取。重复使用相同的 save_as 会更新已保存的爬取，而不是不断创建重复项。保存需要 admin 范围的凭据（因为这会创建可重复使用、可调用的配置）；运行则只需 run。

需要登录的网站（writ_personas）

Persona 是已保存的登录身份，包含用户名、在服务端封存的凭据、可选的双重身份验证（2FA）以及保持登录状态的会话。writ_personas 可以列出你的 Persona（包括各自的就绪状态）、查看某个 Persona（get）、通过运行其登录工作流刷新会话（sign_in），或者让 AI 记录一次登录流程，以便该 Persona 此后能自行登录（record_login）。随后，助手会将 persona_id 传给 writ_run_workflow（以及各个固定的 run_<name> 工具）、writ_crawl_site 或 writ_scrape；在 Writ Cloud 上，也可传给 writ_browser_use。任务便会以登录状态运行，2FA 验证码由服务端生成。

按照设计，连接器只能使用 Persona，不能管理它们：创建、编辑或删除 Persona 都涉及凭据，而任何凭据或一次性验证码都不会通过 MCP 连接向任一方向传输。Persona 在 Writ 控制面板中创建。

如果工具调用超时

调用会返回 status: "running" 和 retryable: true。运行并未取消——再次调用该工具会启动第二次运行。请先等待，然后使用足够大的 max_age 重试，以便在第一次运行完成后获取其结果。

配置

标志的优先级高于环境变量。

标志	环境变量	默认值	用途
--url	WRIT_COORDINATOR_URL / WRIT_URL	https://api.usewrit.app	目标基础 URL。路径已经是 /mcp 或 /mcp/<slug> 的 URL 将按原样使用。
--api-key	WRIT_API_KEY	—（必需）	Authorization: Bearer 所用的密钥。建议使用环境变量。
--insecure	WRIT_INSECURE_TLS=1	关闭	接受自签名的本地 CA 证书。仅限专用网络。
--timeout	WRIT_MCP_TIMEOUT_MS	600000	单次请求超时时间（毫秒）；包括 writ_run_workflow 的长时间等待。
--help / --version	—	—	打印用法或版本信息，然后退出。

**使用本地 CA 的 HTTPS（自托管）：**请信任该 CA（推荐）并使用 https:// 地址，或设置 NODE_EXTRA_CA_CERTS=/path/to/ca.pem。仅在测试 localhost 时使用 --insecure——它会完全禁用证书验证，导致你的密钥暴露给中间人。

安全性

此进程的用途是传递凭据，因此所有可能导致凭据泄露的事项都会被明确警告，而非为了方便而淡化处理。详见 SECURITY.md。

• **密钥只会发送到 --url，不会发送到其他地方。**没有遥测、没有分析、没有更新检查。零依赖项意味着进程中没有任何传递依赖代码可以向外联络；如果这一点发生变化，CI 会导致构建失败。
• **绝不跟随重定向。**将你的 Authorization 标头转发到 Location 标头指定的任意来源，等于把密钥交给你未选择的主机。遇到 3xx 响应时会报错，并提示你将 --url 指向最终 URL。
• **URL 中的凭据会从所有诊断信息中删去。**MCP 客户端会将服务的 stderr 写入磁盘上的日志文件；否则 https://user:pass@host/ 会以明文形式被写入。
• **任何可能导致密钥泄露的情况都会在 stderr 上发出醒目警告：**禁用 TLS 验证、向非回环主机使用明文 http://，或在命令行中传入密钥。
• **重试绝不会导致工作流重复运行。**只会重试只读方法；tools/call 只会发送一次，因为重试可能会重新执行连接器无法感知的副作用。
• 响应大小上限为 32 MB，因此损坏的端点无法让进程不断增长，直至操作系统终止你的会话。
• 每个请求都会得到响应——卡住的 MCP 客户端会对你的助手造成拒绝服务，而此连接器会竭尽全力杜绝这种故障。

**限定密钥权限范围。**除非你实际使用的工具需要更多权限，否则只授予密钥 workflows:read / workflows:execute 权限。

验证安装内容

发布版本由 CI 发布，并附带 npm 来源证明，因此压缩包在密码学上与构建它的提交和工作流相关联：

npm audit signatures

故障排除

症状	原因和解决方法
Unauthorized: … rejected the API key	密钥错误、已停用或缺少所需权限范围。在 Settings → Developers 下重新创建密钥，并授予 workflows:read / workflows:execute 权限。
Cannot reach …	--url 错误，或目标服务已停止。对于自签名证书，请参阅上方的本地 CA 说明。
… redirected (HTTP 301)	反向代理执行了重定向（通常从 http 重定向到 https）。将 --url 指向最终 URL。
The API key contains characters that cannot be sent in an HTTP header	密钥中混入了换行符或控制字符，通常是复制粘贴造成的。请重新复制密钥。
没有列出工具	连接器无法连接到协调器，或密钥被拒绝；请参阅上方各行。连接正常时，即使尚未保存工作流，也始终会列出静态的 writ_* 工具。
工作流没有 run_<name> 工具	派生工具默认关闭，需选择启用。使用 writ_pin_workflow_tool（或应用中的 Expose as MCP tool 开关）固定工作流；它会在下一次 tools/list 时出现，每个账户最多 20 个。无论是否启用，所有工作流都通过 writ_run_workflow 运行。
客户端无法连接且没有错误提示	查看连接器的 stderr；客户端会记录相关日志。Claude Code：~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-<name>/。

状态

可自托管的协调器	支持且已完成端到端验证。
已发布的 /mcp/<slug> 端点	支持。
Writ Cloud（https://api.usewrit.app，未指定 --url 时的默认值）	支持。未传入 --url 时会自动使用。

开发

npm test

没有开发依赖项——测试套件使用 Node 内置的 node:test，并将真实的 index.js 作为子进程运行，连接到模拟 MCP 服务，测试 MCP 客户端使用的同一 stdio 路径。整个过程约需 6 秒。npm publish 会通过 prepublishOnly 自动运行测试。

请参阅 CONTRIBUTING.md——注意两条硬性规则：永久保持零依赖，以及此处不编写任何工具逻辑。

Writ 的其他项目

usewrit/writ	自托管协调器——Web 界面、API 和你的数据。从这里开始。
usewrit/writ-agent	实际执行浏览操作的 Rust 集群工作器。
writ-mcp（本仓库）	MCP 连接器。

许可证

MIT——请参阅 LICENSE。

本软件包特意采用宽松许可，因为它运行在你的 MCP 客户端内部，而不是协调器内部，因此必须能够嵌入任何位置。它所连接的协调器采用 AGPL-3.0-only 许可；这两种许可证不可互换。