### [瓜奇MCP使用方法](https://pmself.com/doc/4156)

**Published:** 2026-11-13T02:09:25

**Author:** admin

**Excerpt:** 瓜奇内容 MCP 让支持 MCP 的 AI 工具读取和管理 WordPress 内容。接入后，你可以让 AI …

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

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

## 先准备地址和账号

1.  确认 WordPress 已启用瓜奇插件，并完成初始化。
2.  准备 WordPress 后台所在站点的 MCP 地址，例如 `https://你的后台域名/wp-json/gqapi/v1/mcp`。前后端域名不同时，不要直接填访客网站的 Node 域名。
3.  在 WordPress 后台「用户」中准备专用账号，并在该用户资料页生成应用程序密码。
4.  确认 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 字符串和请求头格式。能连接但某项操作失败时，再检查该操作所需权限。

## 按这个顺序创建内容

1.  让 AI 调用 `get_content_schema`，读取目标内容类型支持的字段。
2.  多语言内容先调用 `list_languages`，确认语言代码。
3.  需要阅读权限时，先调用 `list_user_groups`，确认已有瓜奇用户组。
4.  需要分类、标签、品牌或社区节点时，先读取现有分类；只有你要求新增且账号有权限时才创建。
5.  有多个前端时，明确目标前端，核对分类归属，避免内容写入后不在目标站点显示。
6.  先创建草稿，记录返回的内容 ID，再用 `get_content` 回读。
7.  在 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 字符串写入文章、截图或公开配置。



---