WordPress Headless

wp-headless-mcp

一个 MCP 服务，让 AI 助手能够读取 WordPress 网站的内容，并安全地协助编辑。

它将公司的 WordPress 网站（页面、文章、自定义文章类型，例如项目或服务、ACF 字段和 Yoast SEO 数据）连接到 Claude 等 AI 客户端。之后，人们可以用通俗的语言询问网站相关问题，或获取内容方面的帮助。

**状态：**首个版本的功能已全部完成，并已在真实的 WordPress 网站上测试，包含 120 个单元测试。

---

什么是 MCP？

模型上下文协议是一种用于将 AI 助手连接到数据和工具的开放标准。MCP 服务会将自身功能描述为：

• **工具：**AI 可以调用的操作，例如“搜索网站”或“列出最新项目”。
• **资源：**AI 可以读取的内容，例如特定页面或网站的内容模型。
• **提示词：**可重复使用的任务模板，例如“检查此页面的 SEO”。

任何兼容 MCP 的客户端（Claude Desktop、Claude Code、Claude API 等）都可以使用同一个服务，无需定制集成。

它解决的问题

许多公司已经在 WordPress 中管理网站内容：服务、案例研究、团队成员、常见问题、产品。当他们在此基础上构建新内容，例如**渐进式 Web 应用（PWA）**时，这些内容往往：

• **难以供 AI 使用。**聊天机器人或助手需要基于可靠信息给出准确、及时的回答，而不是猜测。手动将大模型连接到 WordPress REST API 既重复又容易出错。
• **被锁在管理界面后。**内容和营销团队无法快速询问“哪些页面没有元描述？”或“为我们的新服务起草一篇文章”。
• **缺少开发文档。**PWA 开发者只能通过反复试错来了解文章类型、ACF 字段结构和 REST 负载。

wp-headless-mcp 为所有这些用户提供了一个定义清晰、安全的 AI 网关，连接到网站。

它如何与 PWA 配合

                    ┌────────────────────────────┐
                    │     WordPress website      │
                    │  pages · projects · ACF ·  │
                    │  · Yoast SEO               │
                    └─────────────┬──────────────┘
                                  │ REST API
              ┌───────────────────┴───────────────────┐
              │                                       │
     PWA user interface                        wp-headless-mcp
  (reads REST API directly:                  (AI layer: tools,
   pages, lists, images)                     resources, prompts)
                                                      │
                               ┌──────────────────────┼──────────────────────┐
                               │                      │                      │
                      AI assistant in the PWA   Content team in      Developers in
                      (via the PWA backend      Claude Desktop       Claude Code
                       and the Claude API)

PWA 在常规页面中仍直接从 WordPress 读取内容。MCP 服务与其并行运行，为AI 功能以及网站周边的工具提供支持。

适用对象

网站访客（通过 PWA）

PWA 内的 AI 助手使用公司的自有内容回答问题，并链接到源页面。

• “你们提供哪些产品设计服务？”
• “给我看看你们为零售公司做过的项目。”
• “我该如何联系你们？”

它只能查看已发布的公开内容，不能更改任何内容。

内容和营销团队

员工将 Claude Desktop 连接到网站，以对话方式处理内容。

• “哪些项目缺少特色图片或 SEO 描述？”
• “参照其他案例研究的风格，为我们最新的项目起草一篇案例研究。”
• “更新 Acme 项目的副标题。”（保存为草稿，以供审核）

更改始终保存为草稿或待审核内容。AI 绝不会发布或删除内容。

PWA 开发者

开发者在构建 PWA 时连接 Claude Code。

• “这个网站有哪些文章类型和 ACF 字段？”
• “为项目文章类型生成 TypeScript 类型，包括其 ACF 字段。”
• “给我看看项目的 REST 负载示例。”
• “这个网站是否满足无头模式使用要求？”

代理机构和自由职业者

该服务不限于某一个网站。将其连接到任何满足网站要求的 WordPress 网站，即可为客户添加 AI 功能、审核内容或加快无头模式构建。需要客户项目方面的帮助？请参阅设置和定制工作。

提供的功能

领域	功能	配置文件
内容	搜索整个网站（包括 ACF 字段）；获取或列出文章、页面和自定义文章类型；分类和标签；Markdown 输出	所有
ACF	任意内容项的自定义字段值，以及来自 acf-json 的标签和类型	所有
公司信息	网站名称、标语、组织详情和社交资料（来自 Yoast），以及首页文本	所有
SEO	Yoast 标题、描述、规范 URL、社交图片；逐页审查和全站问题扫描	所有（启用 Yoast 时）
编辑	创建和更新草稿、将已发布内容复制为草稿、更新 ACF 字段、上传媒体、列出草稿	editor
审计	缺失的特色图片、替代文本、元描述、摘要和过时内容	editor
开发者工具	内容模型、ACF 架构、示例负载、TypeScript 类型生成、网站需求和健康检查	dev
提示词	回复访客、SEO 审查、撰写博客草稿、每周内容报告	所有 / editor

访问配置

一个服务，三种配置。配置决定了哪些工具会被启用，因此公开部署也不会意外暴露编辑工具。

配置	适用对象	能执行的操作
public	PWA 中的 AI 助手	读取已发布内容。即使设置了凭据，也绝不登录
editor	内容和营销团队	读取内容，以及创建和更新草稿、执行审计和管理菜单（管理菜单需要 Administrator 权限）
dev	开发者	读取内容，以及获取架构、生成类型、查看负载示例和检查网站

editor 和 dev 配置使用 WordPress 应用程序密码登录，因此仍受 WordPress 自身的用户角色和权限限制。服务会在启动时检查登录状态和用户权限。

设计原则

• 无需安装插件。 服务仅读取标准 WordPress REST API，因此客户端网站无需安装任何额外内容。
• 默认安全。 公开访问仅限只读。编辑者只能处理草稿：已发布内容不可更改，只能复制为草稿以供审核。任何位置都没有删除操作。
• 答案有据可依。 工具会返回来源 URL，方便 AI 引用信息来源。
• 响应简洁精炼。 HTML 会转换为 Markdown，并移除未使用的元数据，从而让 AI 响应更快速、成本更低。
• 适用于不同网站。 系统会自动发现文章类型和 REST 路由，而非将其写死。Yoast SEO 等可选集成仅会在网站支持时显示。

站点要求

要充分发挥 WordPress 站点的功能，应满足以下条件：

1. 将 AI 客户端应能看到的自定义文章类型注册为 show_in_rest => true。
2. 将 ACF 字段组保存到主题的 acf-json 文件夹。
3. 为包含公开内容的 ACF 字段组开启 “Show in REST API”。
4. 为编辑者和开发者配置文件保持启用 Application Passwords（WordPress 默认设置）。Wordfence 等安全插件可能会将其关闭。

dev 配置文件中的 check_site_requirements 工具会为你检查这些条件。

已知限制： ACF 选项页面（例如电话和电子邮件等全站设置）无法通过 REST API 访问，菜单则需要已登录的 Administrator。

开始使用

要求：Node.js 22 或更新版本，以及 REST API 可访问的 WordPress 站点。

无需安装任何内容：MCP 客户端会使用 npx -y wp-headless-mcp 启动服务，并通过环境变量传入设置。至少设置 WP_URL。对于编辑者或开发者配置文件，还需创建 Application Password（wp-admin → Users → Profile → Application Passwords；建议为专用的 Editor 角色用户创建），并设置 WP_USER 和 WP_APP_PASSWORD。所有设置请参阅：Configuration。

此服务也已列入 MCP Registry，名称为 io.github.aj-ua/wp-headless-mcp。

在 MCP Inspector 中试用

npx @modelcontextprotocol/inspector -e WP_URL=http://aj-ua.local -- npx -y wp-headless-mcp

Inspector 会在浏览器中打开。点击 Connect，然后试用工具、资源和提示词。

连接 Claude Code

claude mcp add wp-headless-mcp -e WP_URL=http://aj-ua.local -- npx -y wp-headless-mcp

添加 -e MCP_PROFILE=editor -e WP_USER=... -e WP_APP_PASSWORD=... 以使用编辑工具。

连接 Claude Desktop

将服务添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS），然后重启 Claude Desktop：

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "wp-headless-mcp"],
      "env": {
        "WP_URL": "http://aj-ua.local",
        "MCP_PROFILE": "editor",
        "WP_USER": "mcp-editor",
        "WP_APP_PASSWORD": "<application password>",
        "ACF_JSON_PATH": "/absolute/path/to/wp-content/themes/your-theme/acf-json"
      }
    }
  }
}

连接 PWA 后端

以 HTTP 模式运行服务，并从后端调用它。设置、安全性和可运行的 Claude API 示例请参阅：docs/PWA_BACKEND.md。

配置

所有设置均为环境变量。MCP 客户端在启动服务时传入这些变量（Claude Code 中使用 -e，Claude Desktop 中使用 env）。从源代码运行时，npm 脚本也会读取 .env。

变量	默认值	用途
WP_URL	必填	站点基础 URL，例如 http://aj-ua.local
WP_USER	—	应用程序密码用户（editor 和 dev 配置）
WP_APP_PASSWORD	—	应用程序密码
MCP_PROFILE	public	public、editor 或 dev
WP_CACHE_TTL	60	GET 请求的缓存秒数；0 表示关闭缓存
ACF_JSON_PATH	—	主题 acf-json 文件夹的路径，用于获取 ACF 标签、架构和 TypeScript 类型
MCP_CPTS	auto	自定义文章类型工具：auto、none，或 JSON，例如 [{"postType":"project","singular":"project","plural":"projects"}]
MCP_TRANSPORT	stdio	本地客户端使用 stdio，远程客户端使用 http
MCP_HTTP_TOKEN	—	HTTP 模式的 Bearer token，至少 32 个字符（openssl rand -hex 32）
MCP_HTTP_HOST	127.0.0.1	HTTP 绑定地址；仅在 HTTPS 反向代理之后使用 0.0.0.0
MCP_HTTP_PORT	3333	HTTP 端口
MCP_HTTP_SESSIONS	false	true 表示为每个客户端保留一个会话；默认无状态
MCP_HTTP_SESSION_IDLE_MINUTES	30	会话空闲超时时间
MCP_HTTP_ALLOWED_ORIGINS	—	CORS 允许的浏览器来源，以逗号分隔；留空表示仅允许服务到服务的请求

参考

工具

所有配置：

工具	功能
list_post_types	内容类型、已发布数量和分类法
search_content	关键词搜索；results 来自 WordPress 搜索，acf_matches 来自 ACF 字段
list_posts / get_post	列出或读取任意文章类型；正文为 Markdown，包含 ACF 字段、特色图片和术语
list_<type> / get_<type>	按自定义文章类型生成，例如 list_projects 和 get_project
list_terms	分类、标签和自定义分类法术语
get_acf_fields	单个条目的 ACF 值，包含标签、类型和字段组
get_company_info	站点、组织、社交资料和主页文本
get_seo_meta	单个条目或 URL 的 Yoast SEO 数据和问题（仅限 Yoast）
find_seo_issues	全站 SEO 扫描，统计各类问题数量（仅限 Yoast）

editor 配置：

工具	功能
create_draft	新建草稿，可选择从现有条目复制（copy_from）
update_post	修改草稿或待审核条目；可提交审核
update_acf_fields	设置草稿或待审核条目的 ACF 值，并根据其字段组进行检查
list_drafts	列出草稿和待审核条目，并附带编辑链接
upload_media	从公开 URL 添加图片或 PDF，并设置替代文本
content_audit	检查缺失图片、替代文本、描述、摘要和过时内容
get_menu	以树状结构显示导航菜单（仅限管理员）

dev 配置：

工具	功能
describe_content_model	每种类型的文章类型、REST 路由、分类法字段和 ACF 组
get_acf_schema	完整的 ACF 字段定义
sample_payload	内容路由的原始 REST JSON
generate_ts_types	文章类型的 TypeScript 接口，采用 standard 或 light ACF 格式
check_site_requirements	检查上述站点要求
site_health	PWA 来源的 WordPress 版本、命名空间、插件、HTTPS、时区和 CORS

资源

URI	内容
wp://site/info	站点、组织、文章类型、分类法和检测到的功能（JSON）
wp://post/{type}/{id}	单个条目，以 Markdown 格式呈现，包含 ACF 字段
wp://page/{slug}	单个页面，以 Markdown 格式呈现，包含 ACF 字段

提示词

提示词	配置文件	功能说明
answer_visitor_question	全部	仅根据网站内容回答，并附上链接
seo_review	全部（仅 Yoast）	审核单个内容并提出修改建议
write_blog_draft	editor	按照网站风格撰写文章并保存为草稿
weekly_content_report	editor	近期变更、等待审核的草稿和主要问题

开发

从源码运行

git clone https://github.com/aj-ua/wp-headless-mcp.git
cd wp-headless-mcp
npm install
cp .env.example .env
npm run build

编辑 .env 并至少设置 WP_URL。npm start、npm run dev 和 npm run inspect 都会读取该文件。若要将 MCP 客户端连接到本地构建版本，请使用 node /absolute/path/to/wp-headless-mcp/dist/index.js 替代 npx -y wp-headless-mcp，并将设置作为环境变量传入。

脚本

命令	功能说明
npm run dev	使用 tsx 从源码运行（stdio）
npm run build / npm start	编译到 dist/ 并运行
npm run inspect	针对源码打开 MCP Inspector
npm test	单元测试（vitest），无需网络
npm run lint / npm run format	ESLint 和 Prettier
npm run check	CI 应运行的全部检查：类型检查、lint、格式检查和测试
npm run example:client -- "<question>"	通过服务向 Claude 提问（文档）

测试使用 tests/fixtures/ 中录制的 aj-ua 响应。构建和类型检查使用 TypeScript 7（以 typescript7 安装）。此外还安装了 TypeScript 6.0，仅用于 ESLint 和类型生成器测试，因为 typescript-eslint 和 TypeScript 的 JavaScript API 尚不支持 TypeScript 7。

路线图

• 等 typescript-eslint 支持 TypeScript 7 后，移除 TypeScript 6.0.3 副本。
• 服务运行在公开的 HTTPS 地址后，测试 Claude 的 MCP 连接器（选项 A）。

技术栈

• 基于 Node.js 22 的 TypeScript
• @modelcontextprotocol/sdk 和 zod
• 使用 turndown 将 HTML 转换为 Markdown
• WordPress REST API（核心、ACF、Yoast）
• vitest、ESLint（typescript-eslint）和 Prettier

设置和定制工作

我负责构建和维护 wp-headless-mcp，也承接相关付费工作：

• 设置： 将服务连接到你的 WordPress 网站，映射文章类型和 ACF 字段，并配置访问配置文件。
• 自定义工具： 为你的网站内容模型和工作流添加工具、资源或提示词。
• 适用于 PWA 的 AI 功能： 构建一个根据你自己的内容回答访客问题的助手。
• 团队上手： 帮助你的内容团队在 Claude Desktop 中日常使用它。

可通过 aj-ua.com 或 LinkedIn 联系我。

许可证

MIT