WordPress MCP Server

wp-mcp

@rnaga/wp-mcp 是一个适用于 WordPress 的模型上下文协议（MCP）服务，可将你的网站转变为可由 AI 操作的平台。通过向 Claude Desktop 等客户端开放 WordPress CRUD 基础操作，助手可以按需起草文章、协作修改，并直接将其发布到数据库中，无需进入 wp-admin。

以下是该服务可支持的一些常见场景：

• 通过 Claude Desktop 等 MCP 客户端直接起草、修改和发布文章。
• 检查 WordPress 用户、其角色和权限，以审计网站权限或生成访问报告。

该服务基于 @rnaga/wp-node 构建，内置精选的 MCP 工具集，涵盖文章、用户、评论、术语、修订版本、元数据、选项和网站设置。MCP 服务可以管理以下数据库表／资源：

资源	可执行的操作
文章	创建、更新、读取或删除文章及其修订版本。
评论	管理讨论串，或插入生成的回复。
用户	添加投稿者、调整角色，或通过原生权限检查停用账户。
术语	管理分类、标签和自定义分类法。
元数据	检查、创建、更新或删除文章、用户、评论、术语和网站元字段。
设置与选项	安全切换网站级配置。

你可以启动 STDIO 服务，直接访问数据库；也可以托管 Streamable HTTP MCP 服务，以供远程访问。为方便起见，当 MCP 客户端需要本地桥接来连接 HTTP 服务时，可以使用 CLI 代理。代理的行为类似本地 MCP 服务，同时将请求转发到 HTTP 端点，非常适合不支持 OAuth 或 WordPress Application Password 的客户端。这样，你就能将 MCP 工作流融入现有编辑流程，而无需重新实现 WordPress 业务逻辑。

项目包含一个 CLI（wp-mcp），可帮助你：

• 配置并启动连接到 WordPress 数据库的本地 STDIO MCP 服务；
• 搭建并初始化基于 Express 的 Streamable HTTP MCP 服务（包含 env/TS 样板代码）；
• 使用 OAuth 或 Application Password 验证远程 WordPress 环境，并运行 JSON-RPC 代理，让 MCP 客户端能够安全地访问该环境；
• 检查可用的 MCP 基础操作，并管理存储在 ~/.wp-mcp 下的凭据。

运行此命令以列出可用的 CLI 命令：

npx @rnaga/wp-mcp -- --help

Usage: <command> <subcommand> [options]

Commands:
   local            Local MCP (stdio) server commands
   utils            Utility commands for configuration, debugging, and MCP inspection
   http             Scaffold a TypeScript project for the MCP streamable HTTP server and related tooling.
   remote           Remote MCP server commands

通过结合服务、CLI 实用工具和代理工具，你可以通过 MCP 标准对 WordPress 内容执行 CRUD 操作、管理用户并同步设置，而无需重新实现 WordPress 逻辑。

入门

本地 STDIO 服务

当你可以直接访问数据库时，请运行 STDIO 服务。CLI 会启动一个 MCP 进程，该进程假定本地存在一个 WordPress 用户，并通过 STDIO 向 MCP 客户端提供网站工具。

flowchart LR
  client(["MCP Client<br/>(e.g. Claude Desktop)"])
  stdio(["Local STDIO MCP Server<br/>(wp-mcp CLI)"])
  db(["WordPress Database"])

  client <--> stdio
  stdio <--> db

1. 运行 CLI 以设置数据库连接：

   npx @rnaga/wp-mcp -- local config-set
   

   CLI 会提示你输入 host、port、database name、user 和 password。如果数据库需要 SSL，你可以提供 CA、证书和密钥文件路径，以保护远程访问。随时运行 npx @rnaga/wp-mcp local config，即可查看已保存的值。

2. 配置 MCP 客户端以启动服务。对于 Claude Desktop，打开 Settings → Developer → Edit Config，并将以下内容添加到 claude_desktop_config.json：

   {
     "mcpServers": {
       "wp-mcp": {
         "command": "npx",
         "args": ["-y", "@rnaga/wp-mcp", "--", "local", "start"],
         "env": {
           "LOCAL_USERNAME": "wp-admin"
         }
       }
     }
   }
   

   **激活服务：**保存配置文件，然后退出并重启 MCP 客户端（例如 Claude Desktop）。现在，WordPress 工具将显示在聊天输入框右下角的 MCP 指示器中。 重要： 将 wp-admin 替换为你的 WordPress 用户名。服务器会根据该用户的 WordPress 权限来确定可用的 MCP 基元。例如，管理员角色可以完全访问所有基元（创建、更新和删除文章、管理用户等），而订阅者角色只能使用有限的工具。这种基于权限的筛选可防止意外执行特权操作。若要查看可用的基元，以及每个基元所需的权限和允许的角色：

   npx @rnaga/wp-mcp -- utils list-prims
   

   这会显示一张表格，其中列出基元名称、标题、描述、所需权限和允许的角色。

   可选： 如果你的项目定义了 WordPress 配置清单（例如 src/_wp/config/wp.json），可以提供该清单。在上方的 env 对象中，将 LOCAL_CONFIG 设为配置文件的绝对路径。如果没有自定义配置，请完全省略此环境变量。配置清单架构请参阅 https://rnaga.github.io/wp-node/docs/getting-started/configuration。

   测试 MCP 服务：

   使用 MCP Inspector 进行交互式测试和调试：

   npx -y @modelcontextprotocol/inspector npx @rnaga/wp-mcp local start -u wp-admin
   

   这会在 http://localhost:6274 打开一个可视化界面，你可以在其中浏览可用工具、使用不同参数进行测试，并检查服务响应。

   注意： Inspector 会将其“Environment Variables”面板内容保存在浏览器存储中，并在不同会话间保留。如果你之前在该面板中添加过 PATH 条目进行故障排查，请在界面中手动删除——过期值可能会覆盖服务实际需要的环境变量，且不会被 CLI 标志或脚本更改覆盖。

CLI 标志和环境变量用法参考：

环境变量	CLI 标志	用途	读取时机
LOCAL_USERNAME	--username <value> / -u <value>	要模拟的 WordPress 用户名	local start 使用该值选择 WP 用户，其角色和权限决定可用的 MCP 基元。
LOCAL_CONFIG	--file <path> / -f <path>	WordPress 配置清单位置	local start 使用该值指定自定义 WP 配置 JSON，供初始化钩子使用。
DB_ENVIRONMENT、WP_DB_HOST、WP_DB_PORT、WP_DB_NAME、WP_DB_USER、WP_DB_PASSWORD、LOCAL_MULTISITE、LOCAL_DEFAULT_BLOG_ID、LOCAL_DEFAULT_SITE_ID、LOCAL_SSL_ENABLED、LOCAL_SSL_CA_FILEPATH、LOCAL_SSL_CERT_FILEPATH、LOCAL_SSL_KEY_FILEPATH	(通过 local config-set 使用向导)	本地数据库连接详情	在 local start 之前由密钥存储加载；使用 local config-set 填写这些变量，或提前导出。

MCP 流式 HTTP 服务

当你需要通过互联网提供 MCP 服务，或让远程团队成员连接时，请使用 HTTP 服务。CLI 会搭建一个 Express 应用（参见 src/http/express/index.ts），该应用会公开 MCP 流式 HTTP 传输和 SSE 后备方案，同时复用同一套原语注册表。

1. 搭建项目

   npx @rnaga/wp-mcp -- http init
   

   向导会提示你填写数据库连接详情，创建一个 wp-node 项目，并添加 Express 样板代码及 HTTP 传输所需的 TypeScript 配置。

   生成的目录结构：

   ├── _wp
   │   ├── config
   │   │   ├── index.d.ts
   │   │   └── wp.json
   │   └── settings.ts
   ├── .env
   ├── .gitignore
   ├── index.ts
   ├── package-lock.json
   ├── package.json
   ├── src
   │   └── index.ts
   └── tsconfig.json
   

   在 .env 中填入脚手架工具要求的值，以及本文档后文列出的任何 HTTP 专用环境变量。

2. 在开发环境中运行服务

   npm run dev
   

   这会使用 ts-node，让你无需预先编译即可迭代开发。

3. 构建并在生产环境中运行

   npm run build
   npm run start
   

   编译后的输出会启动与库中 createHttpServer 组装的相同 Express 服务。

通过远程代理 CLI 连接

当你的 MCP 客户端仅支持 STDIO，或不具备完整的 OAuth 支持，但 WordPress 环境可通过 HTTP 访问时，请使用远程代理。代理会将凭据保存在 ~/.wp-mcp 中，并通过正确的 Authorization 标头将 MCP 请求转发到远程服务。

flowchart LR
  client(["MCP Client<br/>(e.g. Claude Desktop)"])
  proxy(["CLI Proxy<br/>(handles OAuth<br/>or WP Application Password)"])
  server(["MCP HTTP Server<br/>(Express instance in this repo)"])
  db(["WordPress Database"])

  client <--> proxy
  proxy <--> server
  server <--> db

1. 进行一次身份验证

   首先，使用 WordPress 应用程序密码凭据或 OAuth 设备流程为代理注册，以便代理代表你的 MCP 客户端签署请求。

   • WordPress 应用程序密码

     npx @rnaga/wp-mcp -- remote login password
     

     提供服务器的授权 URL（例如 http://localhost:3000），然后输入 WordPress 用户名和应用程序密码。凭据会安全存储，以便代理后续运行时自动提供 HTTP Basic 身份验证（WordPress 应用程序密码通过 Basic 方案传输）。

     使用以下命令查看已存储的值：

     npx @rnaga/wp-mcp -- remote config
     

   • OAuth 设备流程

     npx @rnaga/wp-mcp -- remote login oauth
     

     CLI 会调用 /auth/device/start，显示用户代码，并在浏览器中打开验证 URL。完成设备流程后，访问令牌和刷新令牌会写入 ~/.wp-mcp。你可以根据需要重新运行 remote config 或 remote revoke-token。

   如果需要移除已存储的密钥，请使用 npx @rnaga/wp-mcp -- remote config-clear。

2. 启动代理

像配置本地 STDIO 服务一样配置 Claude Desktop（或其他 MCP 客户端），但将命令指向代理：

{
  "mcpServers": {
    "wp-mcp": {
      "command": "npx",
      "args": ["-y", "@rnaga/wp-mcp", "--", "remote", "proxy"],
      "env": {
        "REMOTE_AUTH_TYPE": "oauth",
        "REMOTE_URL": "https://wp-mcp.example.com/mcp"
      }
    }
  }
}

调整 REMOTE_AUTH_TYPE（oauth 或 password）和 REMOTE_URL，使其与你的远程端点相匹配。你也可以在运行时通过 --authType 和 --remoteUrl 传入这些参数。代理会验证你保存的凭据，在 OAuth 令牌将在五分钟内过期时刷新令牌，然后公开一个本地 STDIO MCP 服务，将每次调用转发到远程 HTTP 传输。

启动后，你的客户端会在本地通过 STDIO 通信，而代理会将流量转发到远程 Express 服务。

Streamable HTTP 服务内部机制

Streamable HTTP 部署集成了 Express 中间件，可在每个请求上初始化 WordPress 上下文、注册流式 HTTP 和 SSE 传输，并加入缓存及 OAuth 元数据处理程序。远程服务作为 OAuth 2.0 资源服务器运行——客户端必须提供 bearer 令牌或 WordPress 应用程序密码，服务器本身绝不会充当 OAuth 客户端。发现元数据由 /.well-known/oauth-protected-resource 提供，确保实现符合 RFC 9728。

CLI 的设备代码助手（npx @rnaga/wp-mcp -- remote login oauth）为 MCP 工具提供了适用于终端的流程。它会与服务器的 /auth/device/* 端点通信，将生成的令牌存储在密钥保险库（~/.wp-mcp）中，并使代理能够自动刷新和附加 bearer 凭据。

访问控制

HTTP 层会对 /mcp 和 /sse 应用身份验证，确保只有经过授权的调用方才能协商会话。它支持：

• OAuth Bearer 令牌——通过配置的提供方进行验证，并在 MCP 会话初始化前将访问令牌映射到 WordPress 用户。
• WordPress 应用程序密码——通过 HTTP Basic 身份验证接受，并在服务器端确认 WordPress 用户身份前进行验证。

Bearer 请求验证失败时，服务器会返回符合 RFC 6750 的 WWW-Authenticate 标头，其中包含授权 URI 和请求的作用域，以便客户端顺利恢复。

端点

路径	用途
/mcp	用于客户端到服务器请求及会话生命周期管理的 Streamable HTTP MCP 传输。
/sse	为需要服务器发送事件的客户端提供的旧版 SSE 传输。
/messages	允许 SSE 客户端将用户消息发送回服务器。
/auth/device/start	启动 OAuth 设备授权流程。
/auth/device/poll	轮询 OAuth 设备流程是否完成，并返回令牌。
/auth/refresh	使用刷新令牌换取新的访问令牌。
/auth/revoke	在提供方处撤销访问令牌。
/auth/userinfo	返回与所提供的 Authorization 标头关联的 WordPress 用户。
/auth/password	验证 WordPress 应用程序密码并返回关联用户。
/.well-known/oauth-protected-resource	为发现工具提供 OAuth 资源元数据。

支持的 OAuth 提供方

服务器内置了适用于 GitHub、Google 和 Auth0 的提供方配置文件。每个配置文件都封装了设备代码签发、令牌轮询、刷新和撤销逻辑，可在实例化 HTTP 服务器时接入。若要使用其他身份系统，可通过相同的挂接点提供自己的提供方实现，并保持部署的其余部分不变。

设置 OAuth 提供方

要启用 OAuth 身份验证，需要在所选提供方处注册应用，并在环境变量中配置凭据。

GitHub OAuth 设置

1. 创建 OAuth 应用：前往 GitHub Developer Settings > OAuth Apps > “New OAuth App”
2. 配置应用：
   • 应用名称：应用的显示名称
   • 主页 URL：应用的主页
   • 授权回调 URL：OAuth 回调端点
3. 获取凭据：创建后，记下 Client ID 并生成 Client Secret
4. 设置环境变量：

   OAUTH_CLIENT_ID=your_github_client_id
   OAUTH_CLIENT_SECRET=your_github_client_secret
   

5. 文档：GitHub OAuth Apps 文档

Google OAuth 设置

1. 访问 Google Cloud Console：前往 Google Cloud Console
2. 创建 OAuth 凭据：依次前往 Menu > APIs & Services > Credentials > Create Credentials > OAuth client ID
3. 配置 OAuth 同意屏幕：设置应用名称、用户支持邮箱和受众设置
4. 选择应用类型：选择合适的类型（Web application、Desktop app 等）
5. 获取凭据：记下 Client ID 和 Client Secret
6. 设置环境变量：

   OAUTH_CLIENT_ID=your_google_client_id
   OAUTH_CLIENT_SECRET=your_google_client_secret
   

7. 文档：在 Google Cloud 中设置 OAuth 2.0

Auth0 OAuth 设置

1. 创建应用：在 Auth0 Dashboard 中注册一个 Native Application
2. 配置授权类型：在 Application Settings > Advanced > Grant Types 中启用：
   • Device Code（设备流所必需）
   • Refresh Token（可选，用于刷新令牌）
3. 启用 OIDC Conformant：在 Application Settings > Advanced > OAuth 中，确保启用 OIDC Conformant
4. 配置连接：为应用设置并启用至少一个连接
5. 获取凭据：记下 Client ID、Client Secret 和 Domain
6. 设置环境变量：

   OAUTH_DOMAIN=your-tenant.us.auth0.com
   OAUTH_CLIENT_ID=your_auth0_client_id
   OAUTH_CLIENT_SECRET=your_auth0_client_secret
   

7. 文档：Auth0 设备授权流程

环境变量用法参考

HTTP 服务从环境变量加载配置，通常通过本地 .env 文件、继承的进程环境或托管平台提供的设置来配置。

环境变量	用途	示例值	读取时机
OAUTH_RESOURCE_URL	受保护资源的公开 URL	https://mcp.example.com	包含在 OAuth 资源元数据和 DNS 重绑定保护检查中。
OAUTH_RESOURCE_NAME	受保护资源的显示名称	Example WordPress MCP	在发现元数据中返回。
OAUTH_SCOPES_SUPPORTED	资源支持的逗号分隔范围	openid,offline_access,posts.read	在发现元数据和 WWW-Authenticate 标头中公布。
OAUTH_SERVICE_DOCUMENTATION_URL	资源的文档链接	https://docs.example.com/mcp	在发现元数据中返回。
OAUTH_AUTHORIZATION_URL	授权服务 URL	https://auth.example.com	在错误标头中发送给客户端，并由 CLI 在初始化设备流程时使用。
OAUTH_CLIENT_ID	OAuth 客户端标识符	mcp-remote-server	请求设备代码或刷新令牌时传递给提供商（取决于提供商）。
OAUTH_CLIENT_SECRET	OAuth 客户端密钥（如有需要）	super-secret-value	用于在令牌刷新期间要求使用机密客户端的提供商。
ALLOWED_CORS_ORIGINS	允许用于 CORS 的逗号分隔 HTTP 源	https://claude.ai,https://inspector.modelcontext.com	配置 HTTP 服务的 CORS 策略。
ENABLE_DNS_REBINDING_PROTECTION	为 HTTP 传输启用 DNS 重绑定保护	true	为可流式 HTTP 传输启用 DNS 重绑定保护。
OAUTH_DOMAIN	OAuth 域名（特定于 Auth0）	sample.us.auth0.com	使用 Auth0 Provider 时，用于构建设备和令牌 URL。

如果未提供某个变量，服务会采用安全的默认值（例如，CORS 默认值为 *、DNS 重绑定保护处于禁用状态，并跳过 OAuth 元数据）。只设置提供商要求的值。

开发自定义 MCP 基元

模型上下文协议定义了三种一等基元：工具（可调用的操作）、资源（通过 URI 暴露的可读取资产）和提示词（模板化的消息序列）。此软件包中的 defaultMcpPrimitives 目前提供工具实现，但同样的装饰器 + 注册模式也可用于暴露资源和提示词。以下工作流涵盖脚手架搭建、编写类，以及将其接入各传输方式。

1. 搭建项目脚手架

使用 CLI 初始化 TypeScript 脚手架并安装依赖项。

本地 STDIO 服务

npx @rnaga/wp-mcp -- local init

src/cli/local.cli.ts 中实现的命令会安装 @rnaga/wp-node 和 @rnaga/wp-mcp，放置一个初始版 src/index.ts，复制 tsconfig.json，创建 .gitignore，并在 package.json 中添加 dev、build 和 start 脚本。

生成的目录结构：

├── package.json
├── src
│   └── index.ts
├── tsconfig.json
└── package-lock.json

Streamable HTTP 服务

npx @rnaga/wp-mcp -- http init

此子命令（参见 src/cli/http.cli.ts）会运行 WordPress 提示词、安装相同的依赖项、复制 HTTP src/index.ts 模板，并将 MCP 专用设置追加到 .env 或 .env.<environment>。脚手架搭建完成后，你可以运行 npm run dev 来启动 Express 传输。

2. 实现一个原语类

创建一个文件，例如 src/mcp/example-suite.mcp.ts，并添加一个使用 @mcp 和 @mcpBind 装饰的类。每个 @mcpBind 方法都会接收 MCP 服务实例和运行时元数据，因此你可以在一处注册工具、资源或提示词。

有关 SDK 端到端用法和原语注册示例，请参阅 @modelcontextprotocol/typescript-sdk 仓库。

import { z } from "zod";

import { mcp, mcpBind } from "@rnaga/wp-mcp/decorators";
import { Mcps } from "@rnaga/wp-mcp/mcp";
import type * as types from "@rnaga/wp-mcp/types";

@mcp("example_suite", {
  description: "Example bundle showing tools, resources, and prompts.",
})
export class ExampleSuiteMcp {
  @mcpBind("example_tool", {
    title: "List Options",
    description: "Return the WordPress options table as JSON.",
    capabilities: ["read"],
  })
  example(...args: types.McpBindParameters) {
    const [server, username, meta] = args;

    server.registerTool(
      meta.name,
      {
        title: meta.title,
        description: meta.description,
        inputSchema: undefined,
      },
      async () => {
        const wp = await Mcps.getWpContext(username);
        const options = await wp.utils.crud.options.getAll();

        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(options, null, 2),
            },
          ],
        };
      }
    );

    return server;
  }
}

每个处理程序都会接收相同的元组：

• server – 来自 @modelcontextprotocol/sdk/server/mcp.js 的 McpServer 实例，它提供 registerTool、registerResource 和 registerPrompt。
• username – 附加到会话的 WordPress 身份；调用 Mcps.getWpContext 时传入该值，以便在访问 WordPress API 时执行权限检查。
• meta – 装饰器元数据（name、title、description、功能、角色），你可以在注册原语时复用这些信息。

Mcps.getWpContext 会返回经过填充的 @rnaga/wp-node 上下文。在工具、资源或提示词中使用它来调用 CRUD 辅助函数、收集站点元数据，或在返回 MCP 响应前执行其他逻辑。

3. 在服务入口点注册类

两种传输方式都提供一个 mcps 数组；将你的类添加到该数组中，以便服务在启动时进行配置。类方法中注册的所有原语（工具、资源、提示词）都会提供给已连接的 MCP 客户端。

本地 STDIO 服务

import { createLocalServer } from "@rnaga/wp-mcp/cli/local";
import { ExampleSuiteMcp } from "./example-suite.mcp";

(async () => {
  const mcpServer = await createLocalServer({
    username: process.env.LOCAL_USERNAME,
    mcps: [ExampleSuiteMcp],
  });

  // connect transport...
})();

Streamable HTTP 服务

import { MemoryCache } from "@rnaga/wp-mcp/http/cache/memory-cache";
import { createHttpServer } from "@rnaga/wp-mcp/http/express";
import { ExampleSuiteMcp } from "./example-suite.mcp";

const app = createHttpServer({
  cacheClass: MemoryCache,
  mcps: [ExampleSuiteMcp],
});

启动服务（本地运行 npm run dev，或构建后运行 npm start），通过本地代理或 HTTP 传输连接的任何 MCP 客户端都可以使用已注册的工具、资源和提示词。

MCP Registry

此服务已发布到 Model Context Protocol Registry，让 MCP 客户端能够轻松发现和安装它。

你可以在此处找到该服务： https://registry.modelcontextprotocol.io/v0/servers?search=wp-mcp&version=latest

Registry 条目包含配置详情、必需的环境变量和安装说明。