瓜奇MCP使用方法

瓜奇内容 MCP 让支持 MCP 的 AI 工具读取和管理 WordPress 内容。接入后，你可以让 AI 查询现有文章、创建草稿、修改内容、上传媒体，再按你的要求发布。

本文介绍的入口是 /wp-json/gqapi/v1/mcp。它与页面构建器 MCP 是不同的入口，不直接负责设计页面布局。

先准备地址和账号

确认 WordPress 已启用瓜奇插件，并完成初始化。
准备 WordPress 后台所在站点的 MCP 地址，例如 https://你的后台域名/wp-json/gqapi/v1/mcp。前后端域名不同时，不要直接填访客网站的 Node 域名。
在 WordPress 后台「用户」中准备专用账号，并在该用户资料页生成应用程序密码。
确认 AI 工具支持远程 HTTP MCP，并能设置认证请求头。

应用程序密码不是普通登录密码。如果用户资料页没有这个入口，需要先检查 WordPress 是否允许应用程序密码，以及站点 HTTPS 和相关安全设置。

账号需要哪些权限

操作	权限要求
连接 MCP	通过身份验证，且拥有 `edit_posts`。
编辑内容	拥有对应内容类型的编辑权限；修改已有内容还会检查该条内容的编辑权限。
管理页面	还需要 `edit_pages`。
发布或定时发布	需要对应内容类型的发布权限。不能只凭“能保存草稿”判断可以发布。
上传和查询媒体	需要 `upload_files`。
创建、修改或删除分类	需要对应分类法的管理权限。

瓜奇用户组用于网站业务权限，与 WordPress 后台角色不同。给某个瓜奇用户组开放阅读权限，并不会赋予 AI 账号后台发布权限。

生成认证字符串

瓜奇支持把 用户名:应用程序密码 编码成 Base64，再放入 Bearer 请求头。BASE64(...) 只是格式说明，不能原样填写。

在 Windows PowerShell 中，将占位文字替换为实际凭据后运行：

$token = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("你的用户名:你的应用程序密码"))
$token

如果客户端要求完整的 Authorization 请求头，填写：

Bearer 生成出来的Base64字符串

如果客户端有单独的 Bearer Token 输入框，只填 Base64 字符串，不加 Bearer 前缀。不要填写 Bearer BASE64(用户名:应用程序密码)。

接口也支持 WordPress 应用程序密码的 Basic 认证。按客户端支持的方式选择一种即可。Base64 不是加密，生成的字符串应像密码一样保管。

在 AI 工具中添加服务

设置项	填写内容
服务名称	自定义，例如 `guaqi`。多站点时使用容易区分的名称。
连接类型	远程 HTTP MCP；客户端可能标为 Streamable HTTP、HTTP MCP 或 Remote MCP。
服务地址	`https://你的后台域名/wp-json/gqapi/v1/mcp`
认证	Bearer Token，或自定义 `Authorization` 请求头。

这个 MCP 入口主要接收 POST 请求。直接在浏览器地址栏打开它，不能作为连接是否成功的判断依据。

Codex 命令示例

可以用下面的命令添加服务。第二行设置当前终端的环境变量，第三行保存到 Windows 用户环境变量，供后续启动的程序读取。

$token = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("你的用户名:你的应用程序密码"))
$env:GUAQI_MCP_TOKEN = $token
[Environment]::SetEnvironmentVariable("GUAQI_MCP_TOKEN", $token, "User")
codex mcp add guaqi --url https://你的后台域名/wp-json/gqapi/v1/mcp --bearer-token-env-var GUAQI_MCP_TOKEN
codex mcp list

列表中出现 guaqi，只说明配置已写入。已经打开的 Codex 进程需要重新启动，并确保能读取新环境变量；接下来还要执行一次实际工具调用。

先做一次只读检查

在 AI 工具中输入：

请调用 guaqi MCP 的 mcp_usage_guide 和 list_content_types，读取使用说明，并列出当前账号可用的内容类型。先不要修改任何内容。

当前内置类型包括文章、页面、商品、社区帖子、链接和文档。实际返回结果还受已注册功能和账号权限影响，扩展插件也可以增加类型。成功返回真实工具结果，才说明认证和连接已通过。

认证失败时，依次检查后台域名、用户名、应用程序密码、Base64 字符串和请求头格式。能连接但某项操作失败时，再检查该操作所需权限。

按这个顺序创建内容

让 AI 调用 get_content_schema，读取目标内容类型支持的字段。
多语言内容先调用 list_languages，确认语言代码。
需要阅读权限时，先调用 list_user_groups，确认已有瓜奇用户组。
需要分类、标签、品牌或社区节点时，先读取现有分类；只有你要求新增且账号有权限时才创建。
有多个前端时，明确目标前端，核对分类归属，避免内容写入后不在目标站点显示。
先创建草稿，记录返回的内容 ID，再用 get_content 回读。
在 WordPress 后台检查正文、图片、价格、权限和语言，确认后再要求发布。

可处理的业务字段包括商品类型与规格、社区悬赏或投票、链接图标、文档上下篇、SEO、FAQ，以及支持这些功能的内容类型上的下载、视频、音频和画廊。不同类型的字段不能混用，以实际 schema 为准。

可以直接这样描述任务

帮我创建一篇简体中文文章，标题是“新手建站指南”。先查询“教程”分类和现有标签，围绕 WordPress 建站流程写内容，保存为草稿，最后回读并告诉我内容 ID。

先读取商品字段说明，再创建一个 T 恤商品。颜色为红色、黑色，尺码为 M、L、XL。每个规格组合分别设置价格和库存，缺少的数据先列出来，保存为草稿。

创建一个不需要物流的虚拟商品，名称为“会员套餐”，价格为 99 元。先核对币种和商品类型；这里只创建商品，不要假定购买后会自动授予 VIP。保存为草稿。

添加一个链接，名称为 Example，网址为 https://example.com。先查询链接分类和“工具站”标签，再使用我提供的图标，填写 SEO，保存为草稿。

创建一篇“安装说明”文档，按操作顺序写正文并设置 FAQ。先确认文档 ID 123 和 456 是否适合作为上一篇、下一篇，再保存为草稿。

处理多语言和图片

启用语言不会自动产生译文。MCP 的 prepare_content_translation 会准备目标语言草稿和待翻译字段，由当前 AI 客户端翻译，再通过 apply_content_translation 写回；这一步不会自动调用网站配置的翻译服务。

普通分类、标签、品牌、商品属性和文档分类可以建立语言关系。社区节点和话题标签不按语言拆分；创建社区节点时，需要按网站语言列表填写各语言名称。已有语言关系的分类不能通过普通更新强行换成另一种语言。

已有媒体优先复用附件 ID 或可用 URL。外部图片可以通过 URL 导入媒体库；不要把 AI 工具电脑上的本地路径当作 WordPress 服务器路径。

客户端本地文件可通过 /wp-json/gqapi/v1/mcp/upload 上传，使用相同认证和 file 文件字段。Base64 上传工具有 10MB 限制；普通文件上传仍受 WordPress、PHP 和服务器上传限制。

发布后怎么确认

先回读内容，检查最终状态是否确实为已发布；再打开目标前端、目标语言的页面。权限内容还要分别用游客和目标用户组账号检查，管理员可见不代表访客可见。

建议给 AI 使用独立账号，重要内容先保存草稿。停用接入时，可在 WordPress 用户资料中撤销对应应用程序密码。不要将密码或 Base64 字符串写入文章、截图或公开配置。