MCP 文字通讯远程

WordPress MCP 服务器的 stdio- to- HTTP 通过代理服务器

将克洛德桌面等AI助手连接到你的WordPress站点,使用包括OAuth 2.0,JWT令牌,以及应用程序密码在内的多种认证方法.

特征

• MCP OAuth 客户端 - 授权编码PKCE、经验证的发现、签发人证书和协调更新
• 带 PKCE 的 OAuth 2.1 - 与PKCE(RFC 7636)的安全授权代码流动
• 资源指标 - RFC 8707 为象征性的观众装订
• 动态客户注册 - RFC 7591支持客户自动登记
• 保护资源元数据发现 - RFC 9728用于自动发现终点
• 多重认证方法 - OAuth 2.1、JWT标志和WordPress应用程序密码
• 持续托肯存储 - 自动验证安全储存的OAuth令牌
• 多机构协调 - 锁文件防止认证冲突
• 自动调试管理 - 处理验证、刷新和清理
• 强化错误处理 - 有适当分类的详细错误信息
• 综合日志 - 结构化伐木,分类和级别
• 完成 MCP 支持 - 工具、资源、提示等

何时使用此代理

如果您的 MCP 客户端支持可流的 HTTP 传输,并可以认证到您的站点,则直接连接到 MCP 适配器端点. 你不需要这个代理 例如,Claude Code(英语:.mcp.json),使用应用程序密码:

{
  "mcpServers": {
    "wordpress": {
      "type": "http",
      "url": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
      "headers": {
        "Authorization": "Basic <base64 of username:application-password>"
      }
    }
  }
}

其他客户端使用自己的配置格式. 检查客户端的远程或HTTP MCP服务器文档.

当其中之一适用时使用代理 :

1. 你的客户只支持Stdio. 它可以启动本地命令,但不能连接到HTTP MCP服务器.
2. 你的客户端无法认证你的网站要求的方式. 代理可以发送应用程序密码,JWT令牌,WooCommerce密钥,或 自定义信头,它可以运行 OA 流量 并且为不能的客户存储代币.
3. 你的交通必须经过代理. 设定 SOCKS_PROXY, (中文(简体) ), HTTPS_PROXY, (中文(简体) ), ALL_PROXY 或者说 HTTP_PROXY 通过它来请求路径。 在 macOS 上设定 USE_SYSTEM_PROXY=true 来使用系统 PAC 文件或 SOCKS 代理.
4. 你的网站很慢或者不可靠. WP_API_TIMEOUT_MS 财务报告和审定财务报表 WP_API_INIT_TIMEOUT_MS 设置超时,初始化失败后返回已退化的响应而不是断开的连接(见 转发行为) (中文(简体) ).
5. 您需要本地连接记录 . LOG_FILE 与 LOG_LEVEL=3 日志每个转发的方法加连接和认证事件(见 逻辑分析) (中文(简体) ).
6. 你正在构建一个一揽子整合. 工具呼叫钩 /lib 捆绑可以在代理认证的连接上发送额外的请求,例如用于使用遥测.

快速启动

安装

npm install @automattic/mcp-wordpress-remote

配置

添加到您的 MCP 客户端配置中( 例如 Claude 桌面) claude_desktop_config.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server"
      }
    }
  }
}

自定义信头

您可以在所有 API 请求中添加自定义信头 CUSTOM_HEADERS 环境变量。 这对API密钥,自定义认证或其他信头要求有用.

JSON格式( 建议):

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "CUSTOM_HEADERS": "{\"X-MCP-API-Key\": \"*Ibo7tweixlbfuwaiufxgakjyefctwajcetb*\", \"X-Custom-Header\": \"value\"}"
      }
    }
  }
}

逗号分隔格式 :

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "CUSTOM_HEADERS": "X-MCP-API-Key:IOskncfyes78U8on3q7ry43o487tybrc,X-Custom-Header:value"
      }
    }
  }
}

命令行使用量 :

CUSTOM_HEADERS='{"X-MCP-API-Key": "wc_mcp_FaQduhQcW0mfVaZgP3yaaqDuXaZ3mw7j"}' \
WP_API_URL="https://your-site.com/wp-json/mcp/mcp-adapter-default-server" \
npx @automattic/mcp-wordpress-remote

自定义信头包含在 :

• 所有 WordPress API 请求
• OAuth 发现请求
• OAuth 令牌交换请求
• OAuth 客户注册请求

第一个运行

1. 启动您的 MCP 客户端 (克洛德桌面等
2. 选择认证方法 基于您的偏好:
   • OAuth 2.0 数据启用 OAUTH_ENABLED=true 打开浏览器以获得授权
   • JWT 托肯语Name设置 JWT_TOKEN 环境变量
   • 应用程序密码设置 WP_API_USERNAME 财务报告和审定财务报表 WP_API_PASSWORD
3. 开始使用 WordPress 特性 在你的人工智能助手

WordPress MCP 插件

安装 MCP 适应器 您 WordPress 网站上的插件 。 一旦激活,它就会在 /wp-json/mcp/mcp-adapter-default-server 设置 WP_API_URL 到完整 URL( 整个 README 中的例子显示模式) 。 要瞄准自定义服务器 ID 或 取名空间, 请通过该服务器的全部 URL .

转发行为

代理将 MCP 客户端的消息转发到已配置的端点并返回服务器的消息. 它不发送自己的初始化探测器,不选择一个MCP版本,也不注册一套固定的方法. 客户端和服务器拥有版本谈判,能力和结果验证. 请求,通知,服务器请求,ID,和元数据通过桥段出行;JSON和SSE响应得到支持.

对于基于初始化的MCP连接,服务器所选择的版本和会话ID被使用在之后的HTTP头. 载有的请求 io.modelcontextprotocol/protocolVersion 内 params._meta 直接使用该版本,不需要代理生成的握手. 这删除了代理版本的许可列表;它不会在协议修订之间翻译,或建立与每一个更新的传输功能的完全相符合.

现有的认证,自定义信头,超时,记录,信使存储,以及系统代理设置仍然可用. 空域 WP_API_URL 现在决定 /?rest_route=/mcp/mcp-adapter-default-server。完整的端点 URL 仍然可以配置。 存档 wordpress-mcp 插件的只使用方法的请求格式和自动传输回落已被删除.

如果上游连接在初始化过程中失败,则代理机保留其已退化的响应 experimental.connectionFailed 并且没有可用的能力,使用客户端提供的版本. 后续行动请求在当地被驳回。 服务器生成的JSON-RPC错误被转发而不是转换成成功的握手. 代理服务器不会默默地重新初始化或重试失败的客户端请求.

工具呼叫钩和 wpRequest 从 /lib 当代理运行时, 捆绑共享已验证的直播连接 。 钩子反应仍然是内部的,钩子失败无法改变客户端的反应. 独立 wpRequest 保留其结果返回接口和可选会话恢复;其现有的参数形状被编码为标准JSON-RPC.

认证方法

1. OAuth 2.1(建议)

OAuth 2.1使用具有PKCE S256的公有本地客户端,验证了MCP的发现,并协调了符号更新. 见 OAuth 客户端行为 用于支持的配置文件、迁移行为和可选特性.

对于自带的WordPress网站:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "OAUTH_ENABLED": "true"
      }
    }
  }
}

MCP 授权特性 :

• OAuth 2.1 授权代码流量 使用PKCE(RFC 7636)
• 资源指标 (RFC 8707)用于象征性的观众装订
• 动态客户注册 (RFC 7591) 当得到支持时
• 保护资源元数据发现 (RFC 9728) (法语)
• 授权服务器元数据发现 (RFC 8414) (中文(简体) )

福利:

• 符合MCP 2026-07-28授权要求的公共本地客户授权
• 加强保护PKCE的安全
• 共享浏览器授权和在支持时刷新更新
• 用自动验证安全存储的托肯
• 自动发现终点
• 不需要管理密码
• 自动过期处理

2. JWT托肯认证

对于服务器对服务器认证,或者当 OAuth 不可用时.

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "JWT_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

3. WordPress应用密码(Legacy)

使用WordPress用户名和应用程序密码进行基本认证.

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "your-username",
        "WP_API_PASSWORD": "your-application-password",
        "OAUTH_ENABLED": "false"
      }
    }
  }
}

要创建应用程序密码 :

1. 转到您的 WordPress 管理员仪表板
2. 导航到用户 > 简介
3. 向下滚动到“ 应用密码 ”
4. 为 MCP 访问创建新的应用程序密码

高级配置

自定义 OAuth 设置

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "OAUTH_CALLBACK_PORT": "7665",
        "OAUTH_HOST": "127.0.0.1",
        "WP_OAUTH_CLIENT_ID": "your-custom-client-id"
      }
    }
  }
}

WooCommerce 整合

对于WooCommerce的特定工具和报告:

{
  "mcpServers": {
    "wordpress": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WOO_CUSTOMER_KEY": "ck_your-consumer-key",
        "WOO_CUSTOMER_SECRET": "cs_your-consumer-secret"
      }
    }
  }
}

环境变量

禁用 OAuth

只使用 JWT 或 Basic Auth :

{
  "env": {
    "OAUTH_ENABLED": "false",
    "JWT_TOKEN": "your-jwt-token"
  }
}

发展模式

用于开发和测试,您可以使用本地寄存器:

设置

1. 清除仓库 :

   git clone https://github.com/Automattic/mcp-wordpress-remote.git
   cd mcp-wordpress-remote
   

2. 安装依赖性 :

   npm install
   

3. 构建工程 :

   npm run build
   

配置

配置您的 MCP 客户端以使用本地版本 :

{
  "mcpServers": {
    "wordpress": {
      "command": "node",
      "args": ["/path/to/your/mcp-wordpress-remote/dist/proxy.js"],
      "env": {
        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server"
      }
    }
  }
}

发展 工作流量

• 监视模式 : npm run build:watch - 在文件更改时自动重建
• 测试 : npm test - 运行测试套房
• 类型检查 : npm run check - 运行类型脚本和 Pretier 检查

托肯管理

OAuth 托肯存储

托肯自动存储在 :

~/.mcp-auth/wordpress-remote-{version}/

手工管理

# View stored tokens
ls -la ~/.mcp-auth/wordpress-remote-*/

# Clear all tokens (forces re-authentication)
rm -rf ~/.mcp-auth/wordpress-remote-*/

# Clear tokens for specific version
rm -rf ~/.mcp-auth/wordpress-remote-0.2.1/

托肯安保系统

• 安全文件权限 (600) 在所有令牌文件中
• 自动签名验证 在每次请求之前
• 已过期的令牌清理 启动期间
• 版本隔离 - 每个版本分别存储符号

多种精神支持

代理在多个实例之间自动坐标 :

• 锁定文件 防止同时 OAuth 流量
• 进程协调 确保每次只有一个认证
• 美丽的等待 当另一个实例正在认证时
• 自动清理 固定锁

如果您看到“ 等待其他例子” 消息, 这是正常的行为 .

解决问题

认证问题

OAuth 浏览器不打开 :

• 检查是否有3000端口可用
• 尝试不同的端口 OAUTH_CALLBACK_PORT
• 手动打开日志中显示的 URL

OAuth 授权失败 :

• 校验 WordPress 站点已安装并启用 MCP 插件
• 检查 WordPress 管理员权限
• 尝试清除令牌并重新认证

JWT 认证失败 :

• 验证 JWT 令牌有效且未过期
• 检查令牌格式和编码
• 确保 WordPress 站点支持 JWT 认证

Basic Auth 失败 :

• 验证用户名和应用程序密码
• 检查应用程序密码已激活
• 确保用户有足够的权限

连接问题

API 端点未找到 :

• 校验 MCP 适应器 插件已安装并激活
• 确认 WP_API_URL 在服务器路由(如:. …/wp-json/mcp/mcp-adapter-default-server(中文(简体) )

权限被拒绝 :

• 检查 WordPress 中的用户权限
• 验证认证证书
• 审查 WordPress 用户角色

港口冲突

如果已使用3000端口 :

{
  "env": {
    "OAUTH_CALLBACK_PORT": "8080"
  }
}

多事件信件

当多个MCP客户端同时启动时"等待其他实例"消息是正常的. 系统协调认证以预防冲突.

逻辑分析

启用详细记录 :

{
  "env": {
    "LOG_LEVEL": "3",
    "LOG_FILE": "/path/to/logfile.log"
  }
}

日志级别 :

• 0 - 只有错误
• 1 - 警告和错误
• 2 - 信息、警告和错误(默认)
• 3 - 调试、信息、警告和错误

安全特性

• 安全 OAuth 流量 带有状态参数和 PKCE
• 脚本加密 安全文件权限
• 自动验证 在每次API 请求之前
• 已过期的令牌清理 并刷新处理
• 多机构协调 防止认证冲突

所需资源

• 节点.js 22+ (需要获取 API 支持)
• WordPress 站点 与 MCP 适应器 安装并激活插件
• WordPress 用户账户 在有适当许可的情况下

许可证

GPL v2 或较后版本

捐款

欢迎捐款! 该项目由Automattic Inc维护.

支助

• 问题: GitHub 问题
• 联合国 检查上面的故障排除区域
• WordPress MCP 插件 : WordPress/ mcp 适应器

需要帮忙吗? 检查 排除故障区域 或打开一个问题.