WP MCP Bridge

WordPress MCP桥

通过模型上下文协议（MCP）将您的WordPress网站连接到Claude.ai，让Claude以只读方式访问您的插件、主题、帖子类型、自定义字段、数据库、源文件、日志、钩子等。

______________________________________________________________________

它做什么

WordPress MCP Bridge将您的WordPress站点转换为Claude.ai可以连接的MCP服务器。一旦连接，Claude可以实时检查您站点的架构——插件、数据库模式、源代码、ACF字段、REST路由、cron作业等——因此它可以编写插件、调试问题并回答以下问题 完全根据您的具体设置量身定制.

克劳德获得只读访问权限。它不能写入、删除或修改任何内容。

______________________________________________________________________

特性

• 完整的OAuth 2.1授权服务器 使用PKCE（S256）、动态客户端注册（RFC 7591）和自动发现端点（RFC 8414+RFC 9728）
• 承载令牌认证 作为OAuth的一个更简单的替代方案——永不过期
• 可配置的OAuth令牌生命周期 --1小时、24小时、7天或30天，可从管理员设置页面切换。紧急“全部撤销”按钮，立即失效。
• 19个MCP工具 涵盖WordPress网站的每个主要方面
• 符合MCP规范2025-11-25 --最新规范，包括 client_id_metadata_document_supported，范围在 WWW-Authenticate，以及 description 在 serverInfo
• 速率限制 --每个IP每分钟120次工具调用
• 加强安保 --路径遍历保护、凭据编校、一次性身份验证码、点击劫持保护等
• 兼容Apache+FastCGI --内置授权标头规范化
• 零依赖 --纯WordPress，无需编写编辑器

______________________________________________________________________

需求

______________________________________________________________________

安装

1. 将此存储库下载或克隆到您的 wp-content/plugins/ 目录：

   cd wp-content/plugins
   git clone https://github.com/your-repo/wp-mcp-bridge.git wp-mcp-bridge

1. 从以下位置激活插件 WordPress管理员→ 插件.
2. 首选 设置→ MCP电桥 查找您的端点URL和承载令牌。
3. 刷新重写规则： 设置→ 永久链接→ 保存更改.

______________________________________________________________________

连接到Claude.ai

有两种连接方法。选项A是最快的。

选项A——承载令牌（最简单）

1. 在Claude.ai中，请访问 简介→ 设置→ 连接器→ 添加自定义连接器.
2. 粘贴您的 MCP端点URL （在设置中找到→ MCP桥）：

   https://your-site.com/wp-json/mcp/v1/bridge

1. 将身份验证类型设置为 持有者令牌 （或 API密钥).
2. 从设置页面粘贴令牌。
3. 保存--Claude.ai立即连接。

选项B-OAuth 2.1（浏览器登录流）

Claude.ai将通过以下方式自动发现OAuth服务器 .well-known/ 端点。如果手动询问OAuth详细信息，请使用：

Claude.ai将打开一个WordPress网站的浏览器窗口，您可以在其中以管理员身份登录并单击 允许访问.

______________________________________________________________________

端点

______________________________________________________________________

可用的MCP工具

______________________________________________________________________

安全

认证

• 承载令牌存储在 autoload = false --从未加载到常规页面请求中
• 令牌通过以下方式验证 hash_equals() 防止定时攻击
• OAuth令牌生命周期是可配置的 --1小时（默认）、24小时、7天或30天（设置→ MCP电桥→ 令牌持续时间）
• 承载令牌认证 永不过期 --只有OAuth访问令牌是有时间限制的
• 授权码在以下时间过期 10分钟 并且是 一次性使用 --赎回后立即删除
• PKCE S256是 强制性的 --普通代码挑战被拒绝
• 承载令牌和插件配置选项被阻止 wp_get_options 工具
• “撤销所有OAuth令牌” 管理页面上的按钮，用于立即紧急失效

授权

• 只有WordPress管理员(manage_options)可以授予OAuth同意
• OAuth同意页面通过以下方式防止点击劫持 X-Frame-Options: DENY 和 Content-Security-Policy: frame-ancestors 'none'
• PKCE S256是 强制性的 --普通代码挑战被拒绝

文件和数据库访问

• 所有文件操作都包含在 wp-content 使用 realpath() +支持分隔符的路径检查（防止OWASP路径遍历）
• 根据根的满列表验证日志文件路径(WP_CONTENT_DIR, ABSPATH, sys_get_temp_dir())
• 数据库查询仅限于 SELECT 只有； user_pass, user_activation_key，以及 SELECT * on wp_users 被封锁
• 插件自己的API密钥和OAuth重定向URI被阻止 wp_get_options 工具

CORS和网络

• CORS标头的作用域为 claude.ai, app.claude.ai，以及 www.claude.ai 仅
• 通过按请求源检查进行DNS重新绑定保护
• WWW-Authenticate 在401个响应中，Claude.ai指向OAuth发现端点
• Apache+FastCGI授权头规范化--否 .htaccess 需要解决方法

______________________________________________________________________

OAuth流程图

Claude.ai                     Your WordPress Site
    │                               │
    │──GET /.well-known/oauth-protected-resource──▶│
    │◀─── { authorization_servers: [...] } ────────│
    │                               │
    │──GET /.well-known/oauth-authorization-server─▶│
    │◀─── { authorization_endpoint, token_endpoint, registration_endpoint } ──│
    │                               │
    │──POST /mcp/v1/oauth/register──▶│  (RFC 7591 Dynamic Client Registration)
    │◀─── { client_id } ────────────│
    │                               │
    │──GET /mcp/v1/oauth/authorize──▶│  (PKCE code_challenge S256)
    │◀─── redirect to WP login ─────│
    │                               │
    [User logs in as WP admin, clicks "Allow Access"]
    │                               │
    │◀─── redirect with ?code= ─────│
    │                               │
    │──POST /mcp/v1/oauth/token─────▶│  (code + code_verifier)
    │◀─── { access_token, expires_in } ───────────│
    │                               │
    │──POST /mcp/v1/bridge──────────▶│  (Authorization: Bearer )
    │◀─── MCP JSON-RPC response ────│

______________________________________________________________________

故障排除

404 / rest_no_route

1. 首选 设置→ 永久链接 然后单击 保存更改 刷新重写规则。
2. 确认插件处于活动状态。
3. 手动测试端点：

   curl -s -X POST https://your-site.com/wp-json/mcp/v1/bridge \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{}}}'

工作响应以以下内容开头： {"jsonrpc":"2.0","id":1,"result":{...

OAuth rest_cookie_invalid_nonce (403)

已在v2.6.0（BUG-35）中修复。更新到最新版本。同意书现在发送两个单独的nonce：一个用于WordPress REST cookie认证(_wpnonce)一个用于CSRF保护(_mcp_nonce).

授权标头始终为空（Apache+FastCGI）

已在v2.4.0+版本中通过以下方式自动修复 wp_mcp_bridge_fix_auth_header() 功能挂钩 init 优先级1。如果您仍然看到问题，请将此添加到您的 .htaccess:

RewriteRule ^ - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

承载令牌通过 wp_get_options

已在v2.6.0（BUG-31）中修复。插件自己的 wp_mcp_bridge_api_key 选项现在被永久阻止 wp_get_options 工具。

启用调试日志记录

添加 wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

然后检查 wp-content/debug.log 或使用 wp_get_logs MCP工具。

______________________________________________________________________

更新日志

v2.8.0

• 特性 可配置的OAuth令牌生命周期——1小时、24小时、7天或30天（设置→ MCP电桥→ 令牌持续时间）。承载令牌身份验证不受影响。
• 特性 管理员设置页面上的“撤销所有OAuth令牌”按钮用于紧急无效。
• 修复\[高\] BUG-39:MCP协议版本 2025-11-25 （最新规范，发布于2025-11-25）不在支持列表中——Claude.ai的版本总是被降级。现在支持的最高优先级版本。
• 修复\[中等\] BUG-40：缺少授权服务器元数据 client_id_metadata_document_supported 字段——MCP规范2025-11-25要求这样做，以便客户端知道使用DCR，而不是客户端ID元数据文档。
• 修复\[中等\] 问题41： WWW-Authenticate 401标题缺失 scope 参数——MCP规范2025-11-25§受保护资源元数据（SEP-835）要求它用于增量范围同意。
• 修复\[中等\] BUG-42：24小时令牌的同意页面到期显示为“1440分钟”。新 wp_mcp_bridge_format_ttl() 助手显示“24小时”、“7天”等。
• 修复\[低\] 错误43： serverInfo 在 initialize 响应缺失可选 description 由MCP规范2025-11-25添加的字段。
• 修复\[低\] BUG-44：激活时未写入令牌TTL选项——管理员单选按钮在新安装时没有预选值。TTL选项现在被阻止 wp_get_options 工具。

v2.7.0

• 修复\[高\] BUG-36:SQL注入 wp_mcp_tool_db_schema() — esc_like() 使用无 prepare()WordPress文档需要两者。
• 修复\[中等\] BUG-37:OAuth同意随机数经过消毒 sanitize_text_field() 而不是规范 sanitize_key().
• 修复\[低\] BUG-38:v2.6.0审计头中的重复注释块留下了一行未注释的空白，破坏了块注释结构。

v2.6.0

• 修复\[关键\] 错误35： rest_cookie_invalid_nonce 403关于“允许访问”——双随机数形式方法
• 修复\[关键\] 错误-31： wp_get_options 可以暴露插件自己的Bearer令牌
• 修复\[高\] 错误-32: _get_cron_array() 返回 false PHP 8.2上的cron工具崩溃+
• 修复\[中等\] BUG-33：未使用 $resp_types 导致PHP通知的变量
• 修复\[低\] BUG-34:插件停用时未清理瞬态

v2.5.0

• 修复\[关键\] BUG-26：缺失 registration_endpoint --Claude Code无法连接
• 修复\[关键\] BUG-27：插件已声明 Requires PHP: 7.4 但使用PHP 8.0+语法
• 修复\[高\] 错误28： realpath() 返回 false 旁路防护装置
• 修复\[中等\] 错误-29： register_setting() 没有上瘾 rest_api_init
• 修复\[中等\] 错误-30： array_filter() 删除有效的空字符串OAuth参数

v2.4.0

• 修复\[关键\] BUG 20： do_action('rest_api_init') 内部工具回调双触发所有钩子
• 修复\[高\] BUG 21： strncmp 兄弟目录绕过了路径前缀检查
• 修复\[高\] BUG-22:N+1个数据库查询 wp_get_users 工具
• 修复\[高\] BUG-23：未设定的输出 $client_display 变量（XSS风险）
• 修复\[中等\] BUG-24:OAuth同意页面缺失 X-Frame-Options --点击劫持
• 修复\[中等\] BUG-25:Apache/FastCGI上的授权标头被剥离——auth总是失败

v2.3.0

• 修复\[关键\] 错误12： wp_safe_redirect() 阻止OAuth代码传递到 claude.ai
• 修复\[关键\] 错误13： get_json_params() 返回 null 导致PHP 8类型错误
• 修复\[高\] 错误14： wp_enqueue_script('', '') 未排队内联JS句柄
• 修复\[高\] BUG 15： ini_get('error_log') 绕过安全路径--日志遍历漏洞
• 修复\[高\] BUG-16:即使出现错误，令牌回退路径也始终发出HTTP 200
• 修复\[中等\] 错误17： strtok() 全局状态损坏路径解析
• 修复\[中等\] BUG-18:令牌回退响应中缺少缓存控制/Pragma标头
• 修复\[低\] BUG-19：缺失 rel="noopener noreferrer" 上 target="_blank" 链接

v2.2.0版本

• 已实现完整的OAuth 2.1 PKCE授权服务器（BUG-11）
• 添加 /.well-known/oauth-authorization-server （RFC 8414）
• 添加 /.well-known/oauth-protected-resource （RFC 9728）
• 添加 /authorize 和 /token 旧MCP规范兼容性的回退路径

v2.1.0

• 修复\[关键\] BUG-01：缺少GET处理程序导致通用404
• 修复\[关键\] BUG-02：选项飞行前被身份验证回调阻止
• 修复\[关键\] BUG-03:缺少CORS标头阻止了所有Claude.ai响应
• 修复\[高\] 错误-04： post_count 总是投给 1 通过stdClass
• 修复\[高\] BUG-05：缺失 wp_reset_postdata() 在WP_Query循环之后
• 修复\[中等\] BUG-06:API密钥存储在 autoload = true
• 修复\[中等\] 错误-07： date() 代替 gmdate() 用于时间戳
• 修复\[中等\] 错误-08： MCP-Protocol-Version 仅在初始化响应时使用标头
• 修复\[低\] BUG-09：速率限制键被假冒 HTTP_X_FORWARDED_FOR
• 修复\[低\] BUG-10：内联 onclick JS上的“重新生成密钥”按钮

______________________________________________________________________

贡献

欢迎拉取请求。对于重大更改，请先打开一个问题。

报告错误时，请包括：

• WordPress版本
• PHP版本
• 确切的错误消息或HTTP响应
• 输出 curl 针对MCP端点（标记已编辑）

______________________________________________________________________

许可证

GPL v2或更高版本