WordPress MCP Server

一个面向 Cursor、ChatGPT、Codex、Claude 等 MCP 客户端的 WordPress 内容管理服务。它直接调用 WordPress 原生 REST API，不要求在 WordPress 内安装本项目的插件。

核心能力

零 WordPress 插件：默认使用 WordPress 5.6+ 原生 Application Password。
Docker 一键部署：./deploy.sh 或 docker compose up -d --build。
双传输：远程 Streamable HTTP（/mcp）和本地 stdio。
内容管理：文章、页面、自定义 REST 内容类型、分类、标签、媒体、评论。
AI 检索兼容：实现标准 search / fetch 工具，返回可引用的 WordPress 永久链接。
安全默认值：新内容默认草稿；文章、媒体、评论默认软删除；内容类型有显式白名单。
两种 WordPress 鉴权：Application Password 与已有 JWT Bearer Token。

重要的鉴权边界

“零插件”和“JWT”需要区分清楚：

application_password 是推荐默认值。它从 WordPress 5.6 起属于核心功能，不需要额外插件。
WordPress Core 本身不签发通用 REST JWT。jwt 模式只用于你的站点已经通过现有插件、反向代理或身份网关接受 JWT 的情况。本项目不会要求你额外安装插件，但也不会伪装成 WordPress 原生 JWT。
MCP_API_KEY 保护的是 AI 客户端到本 MCP 服务的连接；WP_* 凭据保护的是 MCP 服务到 WordPress 的连接，两者互相独立。

工具

工具	作用	风险属性
`search` / `fetch`	标准检索与完整内容读取	只读
`wp_site_info`	检查站点及 REST 能力	只读
`wp_list_content` / `wp_get_content`	读取文章、页面或白名单中的自定义类型	只读
`wp_create_content` / `wp_update_content`	创建、修改内容	写入
`wp_delete_content`	回收或永久删除内容	破坏性
`wp_list_terms` / `wp_create_term` / `wp_update_term` / `wp_delete_term`	管理分类和标签	读写
`wp_list_media` / `wp_upload_media` / `wp_update_media` / `wp_delete_media`	管理媒体库	读写
`wp_list_comments` / `wp_update_comment` / `wp_delete_comment`	审核、编辑、删除评论	读写

1. 创建 WordPress Application Password

登录 WordPress 后台。
打开“用户 → 个人资料”。
找到“应用程序密码”，输入名称，例如 WordPress MCP Server。
点击“添加新应用程序密码”，立即复制生成的密码；它只显示一次。
建议新建一个专用 WordPress 用户，只授予实际需要的角色。发布、上传、评论管理权限最终由该用户角色决定。

生产环境只使用 HTTPS。Application Password 通过 HTTP Basic Auth 发送，HTTP 明文链路不安全。

2. Docker 一键部署

cp .env.example .env
# 编辑 .env，至少填写 WP_URL、WP_USERNAME、WP_APPLICATION_PASSWORD
./deploy.sh

默认从 ghcr.io/cnmbdb/wp-mcp:latest 拉取生产镜像。可通过 MCP_IMAGE 环境变量固定到版本或提交 SHA 标签。

检查状态：

docker compose ps
curl http://127.0.0.1:3000/health
docker compose logs -f wordpress-mcp

默认 MCP 地址：http://127.0.0.1:3000/mcp。

本地开发：远程镜像 + Compose 补丁 + 源码挂载

GitHub Actions 同时发布 latest 生产镜像与 dev 开发镜像。本机不重复构建基础镜像，使用第二个 Compose 文件补丁服务命令，并把本地源码只读挂载进容器：

docker compose -f docker-compose.yml -f docker-compose.dev.yml pull
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d
docker compose -f docker-compose.yml -f docker-compose.dev.yml logs -f wordpress-mcp

tsx watch 会监控挂载的 src/。若需要固定开发镜像，可设置 MCP_DEV_IMAGE=ghcr.io/cnmbdb/wp-mcp:dev-sha-<commit>。

Compose 默认通过 BIND_ADDRESS=127.0.0.1 只监听本机。若使用反向代理，保持该默认值即可；只有明确需要局域网直连时才改成 0.0.0.0，并同时启用 MCP 鉴权。

JWT 兼容模式

仅当 WordPress 现有入口已经接受 JWT 时：

WP_AUTH_METHOD=jwt
WP_JWT_TOKEN=your-existing-wordpress-jwt

JWT 的签发、刷新和过期策略由你现有的 WordPress JWT 方案或身份网关负责。

自定义内容类型

自定义 Post Type 必须在 WordPress 中以 show_in_rest=true 注册，然后加入白名单：

WP_CONTENT_TYPES=posts,pages,product,portfolio

服务只会访问这里列出的 /wp-json/wp/v2/<type> 路径。

3. 连接 AI 客户端

Codex

远程 HTTP：

codex mcp add wordpress --url https://mcp.example.com/mcp

若启用了 MCP_API_KEY：

export WORDPRESS_MCP_TOKEN='与服务器 MCP_API_KEY 相同的值'
codex mcp add wordpress \
  --url https://mcp.example.com/mcp \
  --bearer-token-env-var WORDPRESS_MCP_TOKEN

不要把真实密钥提交到配置仓库。

Cursor

项目级 .cursor/mcp.json：

{
  "mcpServers": {
    "wordpress": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

也可以用 stdio 直接启动本地 Docker 镜像：

{
  "mcpServers": {
    "wordpress": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/WordPress MCP Server/.env",
        "-e", "TRANSPORT=stdio",
        "wordpress-mcp-server:local"
      ]
    }
  }
}

Claude Desktop / Claude Code

Claude Desktop 可使用上面的 stdio 配置，写入其 claude_desktop_config.json。Claude Code 可添加远程 Streamable HTTP 地址；具体命令以当前客户端版本的 MCP 添加界面或 claude mcp --help 为准。

ChatGPT

把服务部署到稳定的公网 HTTPS 域名，例如 https://mcp.example.com/mcp。ChatGPT 不能访问 localhost。
在 ChatGPT 中打开 Settings → Apps & Connectors → Advanced settings，启用 Developer Mode。
新建 App（旧界面可能叫 Connector），填入公网 /mcp URL。
工具定义变更后刷新 App，让 ChatGPT 重新读取描述。

ChatGPT 公网生产连接建议使用标准 OAuth 身份网关。MCP_API_KEY 是适合支持自定义 Authorization Header 的客户端的轻量保护，不等同于 ChatGPT OAuth；若暂时不接 OAuth，不要把无鉴权的 /mcp 直接暴露到互联网。

4. 本地开发

npm install
cp .env.example .env
npm run dev

可用脚本：

npm run typecheck
npm test
npm run build
npm start

stdio 模式：

TRANSPORT=stdio npm start

注意：stdio 模式下协议走 stdout，日志只写 stderr。

5. 生产部署建议

使用 Caddy、Nginx、Traefik 或云负载均衡终止 TLS，只代理 /mcp 与 /health。
配置 ALLOWED_HOSTS=mcp.example.com，只填主机名，不含协议和端口。
将 .env 放入服务器或密钥管理器，绝不提交真实 WordPress 凭据。
使用专用低权限 WordPress 用户，定期轮换 Application Password。
force=true 会永久删除；正常自动化应保留默认的回收站行为。
媒体上传受 MAX_MEDIA_BYTES 限制，默认 10 MiB。
容器默认非 root、只读文件系统、移除 Linux capabilities。

目录结构

src/
  index.ts             # 传输模式入口
  http-server.ts       # Streamable HTTP /mcp
  mcp-server.ts        # 工具定义与安全注解
  wordpress-client.ts  # WordPress REST API 客户端
  config.ts            # 环境变量校验
test/                  # 配置与 REST 客户端测试
Dockerfile
docker-compose.yml
.env.example

设计依据

OpenAI Apps SDK：MCP Server、工具定义与远程部署指南。
Model Context Protocol 官方 TypeScript SDK：Streamable HTTP 与 stdio 传输。
WordPress REST API Handbook：文章、页面、媒体、分类、标签、评论端点。
WordPress Application Passwords：WordPress 5.6+ 原生 API 鉴权。

License

MIT