cms

Writavo MCP 服务

在 AI 助手中管理 Writavo 网站的内容。通过浏览器登录，迁移现有博客，起草文章，设置分类和署名，添加图片，安排发布时间并发布，全程只需对话。

该服务托管于 https://mcp.writavo.com/mcp（Streamable HTTP，OAuth 2.1），这是通过 MCP 使用 Writavo 的唯一方式。无需安装任何内容，也无需复制密钥：助手会打开 Writavo 页面，你登录后选择网站和允许助手执行的操作，即可完成连接。支持 Claude Code、Claude.ai、ChatGPT、Cursor、VS Code 及任何支持远程 MCP 的客户端。此代码库是该服务所运行工具的源代码，不会作为软件包发布。

完整设置指南，适用于用户和 AI 助手： https://writavo.com/docs/mcp（Markdown： https://writavo.com/docs/mcp.md）。其中包含每种客户端对应的准确命令或配置、登录方式、权限、审批流程，以及所有错误的含义。迁移博客： https://writavo.com/docs/migrate。

如果你是受托安装 Writavo 的 AI 助手： 使用下方对应客户端的命令添加托管服务；随后由用户通过浏览器登录 （无需粘贴任何内容）；然后调用 get_site_info 和 verify_api_key，并告知用户你连接的是哪个网站，以及你可以在那里执行哪些操作。

连接

Claude Code：

claude mcp add --transport http writavo https://mcp.writavo.com/mcp

然后在 Claude Code 中运行 /mcp，并选择 Writavo 登录。或者安装 Claude Code 插件，该插件会同时添加服务和 Writavo 技能：

claude plugin marketplace add SparkleOfficial/writavo-mcp-server
claude plugin install writavo@writavo

Cursor：将 Writavo 添加到 Cursor （或使用 cursor://anysphere.cursor-deeplink/mcp/install?name=writavo&config=eyJ1cmwiOiJodHRwczovL21jcC53cml0YXZvLmNvbS9tY3AifQ==）。

VS Code：将 Writavo 添加到 VS Code （或使用 vscode:mcp/install?%7B%22name%22%3A%22writavo%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.writavo.com%2Fmcp%22%7D）。

**Claude（claude.ai 和 Claude Desktop）：**依次选择 Customize > Connectors > "+" > Add custom connector，输入 URL https://mcp.writavo.com/mcp，然后点击 Connect。

**ChatGPT：**开启 Developer mode（Settings > Security and login），然后在 https://chatgpt.com/plugins 使用 URL https://mcp.writavo.com/mcp 和 OAuth 创建连接。

Codex CLI：codex mcp add writavo --url https://mcp.writavo.com/mcp（此命令会启动登录；codex mcp login writavo 可重新登录）。

Gemini CLI：gemini mcp add --transport http -s user writavo https://mcp.writavo.com/mcp，然后运行 /mcp auth writavo。

**Windsurf 和 Zed：**请参阅 https://writavo.com/docs/mcp#clients。

其他任何支持 JSON 配置的客户端：

{
  "mcpServers": {
    "writavo": { "type": "http", "url": "https://mcp.writavo.com/mcp" }
  }
}

不支持 OAuth 的客户端可以改用 Writavo 密钥作为 bearer token（Authorization: Bearer wv_sk_...，可在 https://app.writavo.com/settings/api-keys 创建）。手动创建的密钥不是 AI Agent 密钥，因此不适用权限选择器、关闭开关和调用日志。建议使用登录方式。

连接时，Writavo 会显示发起请求的助手、将你带回的位置、要连接的站点，以及它可能执行的操作。每个领域对应一行（文章；内容类型和条目；分类、标签和作者；媒体；AI 流水线；站点设置和设计；发布和域名；SEO；外联联系人；读者评论；团队和组织；账单；报告和日志），你可以为每项选择“无访问权限”“读取”或“读取和写入”（流水线为“读取、规划和运行”，会消耗额度；读者评论为“读取和审核”；外联联系人和报告仅支持读取）。这些选项默认采用你组织的默认设置：内容、媒体和站点设置为“读取和写入”，其他项目为“读取”；外联联系人和读者评论除外，因为其中包含他人的姓名和电子邮件地址，除非你主动选择，否则默认关闭。连接会为其访问的每个站点使用一个普通的 Writavo 密钥，该密钥仅限所选权限，并以应用名称命名（“Claude Code (hosted MCP)”）。你可以在 https://app.writavo.com/settings/agents 查看所有已连接的助手及其调用记录，也可以撤销访问权限。

它能做什么

该服务根据 Writavo 发布的 OpenAPI 规范编译了 45 个工具，另有 9 个手动编写的工具：

• 文章。 列出、读取、创建、更新、删除、发布、取消发布、安排发布、取消计划。
• 内容类型和条目。 列出和读取内容类型；列出、读取、创建、更新、删除、发布、取消发布和安排发布条目。
• 分类体系和人员。 分类、标签和作者：列出、读取、创建、更新、删除。
• 媒体。 列出、读取、更新、删除，以及 upload_media。该工具通过一次调用完成整个三步预签名上传流程，因此助手无需协调各个步骤。它接受公开的 url，或通过 base64 提供字节数据并附带 filename。
• 流水线。 触发运行、读取状态、读取队列。
• 元信息。 站点信息、内容类型、套餐用量和余额，以及完全无需密钥的 get_api_docs。
• 登录。 没有登录工具：连接时，服务会通过 OAuth 为你登录。
• 套餐。 start_plan_purchase 会返回预先选好套餐的账单链接。付款在浏览器中的 Stripe 页面上完成，不会在聊天中进行。CMS（存储、发布和导入内容）采用按量付费，无需套餐；购买套餐即可使用 AI 文章流水线。
• 导入。 import_content 可导入现有博客（见下文）。
• 其他所有操作，均作为操作提供。 站点设置和知识档案、组织、文章格式和 AI 提示词、流水线配置和内容计划、投放和域名、SEO、推广、访客分析及其安装检查、读者评论、团队和角色、账单，以及洞察和日志都不是独立工具。search_writavo_actions 接受几个词语（例如“邀请团队成员”“自定义域名”），并返回匹配的操作，每项都包含其输入架构、所需权限范围、是否会先询问、需要审批或需要付费，以及应使用哪个执行器。read_writavo_action 用于执行读取操作（它只会执行 GET 操作，因此客户端可以允许它在无需询问的情况下运行），而 run_writavo_action 则用于执行任何会产生更改的操作；两者都会接收 operation_id，并先根据该操作的架构检查参数。对于助手永远无法执行的请求（例如“添加银行卡”“删除站点”），系统会返回相应说明，以及用户可前往操作的控制面板链接。因此，客户端只需加载几十个工具描述，而不是一百多个；只有在搜索时才会为其余内容付费。

每个工具都带有 MCP 注解：读取操作使用 readOnlyHint，删除和取消发布操作使用 destructiveHint，读取、更新和删除操作使用 idempotentHint，并设置 openWorldHint: false，因为每个工具都只连接到一个封闭系统：你的站点。

导入博客

migrate-content 提示词会引导助手完成整个迁移流程：连接、使用你已有的访问权限检查当前系统、编写导入文件、试运行、修复、导入并验证。Slug 会保留，因此 URL 不会改变；已发布的文章会保留原始发布日期，草稿仍为草稿，图片会复制到你的媒体库中。

该文档是 Writavo Import Format v1，一个 JSON 文档。服务会将其与导入进度一起保存为一个导入项，并存储在 import_id 下（自启动该导入的连接最后一次使用后保留 7 天），因此只需发送一次，后续每次调用只需传入 { "import_id": ... }。有 3 种导入方式，文件大小上限为 10 MB：

• upload: true 会返回一个一次性链接和一条 curl 命令，用于直接将文件 PUT 到服务。最适合能够运行 shell 命令的助手：文件不会经过对话。
• url：服务匿名获取的 https URL（例如已签名的存储 URL）。
• data：直接内嵌文档，每次调用最多 50 篇文章、512 KB（仅适用于小型文档）。较大的文档请分批发送，每批都使用首次调用返回的 import_id；作者按 ref 合并，分类和标签按 slug 合并，文章按 external_id 合并，重复发送的条目会替换已存储的条目。

文档如下所示：

{
  "format": "writavo-import",
  "version": 1,
  "authors": [{ "ref": "jane", "name": "Jane Doe", "is_ai_generated": false }],
  "categories": [{ "slug": "guides", "name": "Guides" }],
  "tags": [{ "slug": "soil", "name": "Soil" }],
  "articles": [
    {
      "external_id": "blog:1001",
      "status": "published",
      "title": "How to test your soil",
      "slug": "how-to-test-your-soil",
      "content": "Markdown, with ![images](https://example.com/kit.jpg)",
      "author": "jane",
      "category": "guides",
      "tags": ["soil"],
      "published_at": "2021-03-04T09:30:00Z"
    }
  ]
}

完整字段列表和 JSON Schema 位于 writavo://import-format 资源中，也可以不带参数调用 import_content。external_id 是你为每篇文章设置的稳定 ID，用它可以让第二次运行更新文章，而不是创建重复项。

除非另有说明，import_content 会进行试运行：它会一次性检查整个文档与站点的匹配情况，并报告将要创建、更新和发布的内容、所有问题（同时列出顶层条目和每篇文章的 external_id）、要复制的图片以及预计耗时，而且不会写入任何内容。发布内容的导入需要设置 confirm: true。随后，应用操作会在 Writavo 的服务上后台运行，直至所有文章处理完毕，并立即返回；{ "import_id": ..., "status": true } 会说明处理进度和耗时分布，cancel: true 会在当前批次处理完后停止。再次发送某篇文章会更新它，而不是创建重复项，因此导入可以安全地重复运行。

同一导入功能也提供 REST API，供非助手使用（例如脚本、命令行或推送文章的其他 CMS）：POST /v1/imports 携带文档，POST /v1/imports/{id}/start，GET /v1/imports/{id}。请参阅 https://writavo.com/docs/migrate。它绝不会删除或取消发布任何内容，除了复制图片的 URL 外，也不会更改你的内容。

未经询问不会执行的操作

publish_article、schedule_article、所有 delete_*、trigger_pipeline_run，以及会发布内容的 import_content，首次调用时都不会执行任何操作。它们会说明将要发生的情况，并等待 confirm: true；只有在你同意后，助手才能设置该参数。发布会将内容放到你的线上站点，删除操作不可撤销，运行流水线则会消耗实际额度。

操作也遵循同样的规则：run_writavo_action 会说明任何会花费资金、更改线上站点、移除内容或更改团队的操作，并等待 confirm: true。

有些操作无论密钥携带哪些权限范围，助手都无法访问：

• API 密钥。 能够生成密钥的服务，一旦遭到入侵，也会生成密钥。
• Webhooks。 能够更改投递 URL 的助手，可以悄悄重定向你的事件流。
• AI Agent 控制项、批准自身请求、付款详情、套餐更改、所有权、删除站点或组织、外联策略和邮箱，以及 CMS 或 Bing 凭据。 get_api_docs（tools 部分）会提供每项对应的控制面板链接，供人员使用。

以上所有操作都只能在控制面板中进行。

审批，以及关闭 Agent

当通过浏览器登录的助手删除内容或取消发布文章时，组织可以要求先由人员审批。此功能默认开启。助手发起涉及花费资金或更改团队的操作时（运行流水线和提高流水线级别、付费 SEO 扫描、自定义域名、发布托管网站、CMS 连接和推送、自动补充、提高信用额度上限、保留套餐、邀请、更改角色和权限、移除成员），无论开关状态如何，都始终需要审批。工具随后不会执行任何操作，并返回一个链接：https://app.writavo.com/approvals/...；你在该页面批准后，助手会带着审批 ID 重试调用，该操作便会执行一次，且仅针对该请求。所有者或管理员可以在 https://app.writavo.com/settings/agents 关闭审批，或为整个组织关闭 AI Agent 访问权限；该页面还会列出每个已连接的助手及其所有调用。你在控制面板中自行创建的密钥不受这两个开关的影响。

它绝不会记录什么

• 连接密钥只会作为 bearer 标头发送到 https://api.writavo.com/v1，不会发送到其他任何地方。没有遥测数据、分析数据或第三方主机。每个请求都会标明发起调用的工具（Writavo-Mcp-Tool），这会填充“设置”>“AI agents”中的调用日志。基础 URL 从规范中读取。除此之外，只有在 upload_media 或导入期间会向预签名存储上传链接发送请求；导入期间还会获取你自己的文件中的图片 URL，以便复制图片。
• 每条回复、日志行和错误信息都会经过脱敏处理，因此即使 API 在错误消息中回显密钥，密钥也不会出现在你的对话记录中。

你可能会看到的错误

每个错误都会说明需要更改什么，而不只是返回状态码。

代码	含义	处理方法
INSUFFICIENT_SCOPE	密钥缺少所需权限范围，或创建者的权限已不再涵盖该范围	使用具有该权限的身份重新连接（登录），或在 https://app.writavo.com/settings/api-keys 为你创建的密钥添加权限范围
NOT_ENTITLED	你的套餐不包含此功能	在 https://app.writavo.com/billing 升级
INSUFFICIENT_CREDITS	组织无法承担下一个工作单元的费用	在 https://app.writavo.com/billing 充值
SPEND_CAP_REACHED	此 Site 已达到你为其设置的月度上限	提高上限或等待重置
NOT_FOUND	对象不存在，或属于其他 Site	确认你使用的是对应 Site 的密钥
AGENT_ACCESS_DISABLED	组织已关闭 AI Agent 访问权限	所有者或管理员可在 https://app.writavo.com/settings/agents 开启
APPROVAL_REQUIRED	此操作需要人员审批	将链接发给对方，等待审批，然后再次调用工具并传入 approval_id
APPROVAL_PENDING	尚无人作出决定	请对方打开链接；获批后再次调用
APPROVAL_DENIED	人员拒绝了审批	无需重试；改为决定接下来怎么做
APPROVAL_INVALID	审批已过期、已使用，或对应的是其他请求	再次调用工具，但不要传入 approval_id
API_KEY_REVOKED / API_KEY_EXPIRED	连接密钥已撤销或过期	重新连接并登录
PAYMENT_METHOD_REQUIRED	已用完包含的 CMS 额度，且账户中没有登记银行卡	在 https://app.writavo.com/billing 添加银行卡；这不是套餐限制

完整目录见 get_api_docs 中的 errors，以及 https://writavo.com/docs/errors。 登录问题（例如浏览器页面提示无法在此浏览器中确认登录、没有可选择的 Site 等）请参阅 https://writavo.com/docs/mcp#troubleshooting。

提示词

• draft-article. 调研某个主题，并用你的网站自己的风格撰写草稿。它绝不会发布或安排发布时间。
• publish-checklist. 检查现有草稿的标题、slug、SEO 字段、摘要、分类、作者和特色图片，然后在发布前征求你的确认。
• migrate-content. 将其他系统中的现有博客忠实地迁移到你的网站，先进行试运行，并在发布任何内容前征得你的确认。它遵循 https://writavo.com/docs/migrate 中的操作手册。

开发

此软件包作为私有工作区软件包位于 Writavo monorepo 中（不会发布到 npm）。工具只在 src/core/ 中实现一次，并导出为 @writavo/mcp-server/core，由托管服务打包：

import { createWritavoMcpServer } from "@writavo/mcp-server/core";

const server = createWritavoMcpServer({
  apiKey: () => key,              // null makes every key-requiring tool say how to connect
  userAgent: "my-host/1.0",
});

软件包中的任何内容都不会读取环境、访问文件系统或在模块状态中保存密钥，因此可以在 Cloudflare Worker 中运行（托管服务正是以这种方式加载它）。它没有本地或 stdio 入口：软件包没有 bin，且只导出 ./core。工具架构、描述和参考文本均为生成内容，而非手写：

npm run build       check the generated tools are current, then compile
npm run gen         regenerate from the vendored openapi.yaml
npm test            run the offline smoke checks (the core over an in-memory MCP client, imports and more, against a stub API)
npm run gen:check   fails if the committed tool surface is stale

添加端点只需在 openapi.yaml 中添加并重新生成；标记了 x-writavo-approval 的操作会自动获得一个 approval_id 参数。标记为工具的 45 个操作各自都是独立工具；所有其他操作都会进入 src/generated/operations.ts 中的 ACTIONS 目录（根据其标签，或操作或标签上的 x-mcp-surface: tool | action），并由 search_writavo_actions、read_writavo_action 和 run_writavo_action 提供服务。编辑 src/generated/ 下的任何内容都会导致 CI 失败。9 个手写工具位于 src/tools/ 中（src/core/server.ts 中的 CORE_LOCAL_TOOL_NAMES），并列在 monorepo 的 scripts/mcp-surface.mjs 中的 LOCAL_TOOLS 内。

许可证

MIT（LICENSE）。可分叉、修改、打包引用，也可将其集成到其他产品中发布。

MIT 许可仅适用于此客户端代码，并不许可使用该软件包调用的 Writavo Content API，也不适用于 Writavo 的任何其他部分。使用 API 仍需要你自己的凭据，并受 https://writavo.com/terms 中条款的约束；openapi.yaml（此软件包据此编译的规范）仍是其一贯的专有契约。

这种区分是有意为之。此代码只是一个精简的生成式客户端：其中没有值得限制的内容，而 MIT 客户端更容易赢得信任并接受审计。产品本身是它背后的 API。