WordPress 7.0 MCP Adapter + Abilities API 实战：让 Claude Code 直接调用你的站点能力

WordPressWordPress 7.0MCPAbilities APIClaude CodeAI 编程

WordPress 7.0 在 2026-05-20 发布时，把两件原本属于"插件圈"的东西搬进了核心：**Abilities API**（统一注册 WordPress 能力的接口）和 **MCP Adapter**（把 Abilities 暴露成 Model Context Protocol 工具的服务端）。配合客户端 Claude Code / Claude Desktop / Cursor / VS Code，AI 就能"像人一样"直接调用你的站点——不是生成 HTML 让你复制粘贴，而是真的去 wp post create、去 wp option update、去 wp comment list。

我从 6/29 写完 wp-config.php 8 项调优那天就开始测，整个链路跑通花了 3 个晚上，期间撞了 4 个真实坑。这篇文章把 4 个坑 + 一份可复制的 claude mcp add-json 命令清单一次性说透。

> 这是一篇开发者向实战文，不是产品评测。文中无任何联盟链接，仅含 1 个官方 GitHub 仓库引用。

🛠️ 前置准备

**WordPress**：7.0（2026-05-20 发布，core 已含 Abilities API + MCP Adapter）
**PHP**：8.2+（推荐 8.3，WordPress 7.0 最低 8.1 但 8.2 才有 readonly class 语法优势）
**Web 服务器**：Nginx 1.28.x 或 Apache 2.4.x，**必须支持 Streamable HTTP**（SSE 已被 MCP 规范弃用，新客户端只认 streamable-http）
**WP-CLI**：2.12.0+（`wp --version` 验证）
**客户端**：Claude Code 2.0+（mattpocock/skills v1.0.1 要求的最低版本刚好对上） / Claude Desktop 0.10+
**认证方式**：WordPress **Application Passwords**（不要用真实账号密码，6/16 那篇安全加固文里我专门强调过这点）

验证命令：

# 确认 WP 版本 + Abilities API 已加载
wp eval 'echo "WP " . get_bloginfo("version") . " | Abilities=" . (class_exists("WP_Ability") ? "yes" : "no") . PHP_EOL;'
# 预期输出：WP 7.0 | Abilities=yes

🚀 核心步骤：把 WordPress 暴露成 MCP 服务

Step 1：安装 MCP Adapter 插件

WordPress 7.0 core 里有 MCP Adapter 代码，但默认没有启用（设计成"按需启用"，避免给最小站点增加攻击面）。

# 切到 wp-content/plugins
cd /var/www/html/wp-content/plugins

# 拉官方插件（不是 Automattic/wordpress-mcp，那个仓库已 deprecated）
# 见 https://github.com/WordPress/mcp-adapter （2026-05-22 GitHub Trending PHP #1）
git clone https://github.com/WordPress/mcp-adapter.git

# 启用 + 验证
wp plugin activate mcp-adapter
wp eval 'echo (function_exists("mcp_adapter") ? "adapter-loaded" : "missing") . PHP_EOL;'
# 预期：adapter-loaded

> 如果你的 WP < 7.0 还想用 MCP Adapter，需要先升级 7.0。7.0 之前的兼容包 Automattic/wordpress-mcp 已**官方废弃**（README 顶部明确写"This repository will be deprecated as the mcp-adapter AI Building Block for WordPress continues releasing stable versions"）。

Step 2：注册一个 Abilities（自定义能力）

MCP Adapter 默认暴露的是 core 的几个基础 Abilities（wp.posts.list 之类），但你想让 AI 做点真正的活——比如"找出本站所有 broken link"、"批量改 SEO description"——必须自己写个 Ability。

WordPress 7.0 的 Abilities API 用 wp_register_ability() 注册一个标准化的能力描述。把它放到一个自定义插件里：

 'Find broken internal links',
        'description' => '扫描全站 published 文章，提取所有 internal link，HEAD 请求检测 4xx/5xx，返回 broken URL 列表。',
        'category'    => 'site-audit',
        'input_schema' => [
            'type'       => 'object',
            'properties' => [
                'limit' => [ 'type' => 'integer', 'default' => 50, 'description' => '最多扫描多少篇文章' ],
            ],
        ],
        'output_schema' => [
            'type'       => 'object',
            'properties' => [
                'broken' => [ 'type' => 'array', 'items' => [ 'type' => 'string' ] ],
            ],
        ],
        'execute_callback' => function ( $input ) {
            $limit   = (int) ( $input['limit'] ?? 50 );
            $posts   = get_posts( [ 'post_status' => 'publish', 'posts_per_page' => $limit ] );
            $broken  = [];
            foreach ( $posts as $p ) {
                preg_match_all( '/href="([^"]+)"/i', $p->post_content, $m );
                foreach ( $m[1] as $url ) {
                    if ( strpos( $url, home_url() ) === false ) continue;
                    $resp = wp_remote_head( $url, [ 'timeout' => 5, 'redirection' => 0 ] );
                    if ( is_wp_error( $resp ) ) {
                        $broken[] = $url . ' (error: ' . $resp->get_error_message() . ')';
                        continue;
                    }
                    $code = wp_remote_retrieve_response_code( $resp );
                    if ( $code >= 400 ) $broken[] = $url . ' (' . $code . ')';
                }
            }
            return [ 'broken' => $broken ];
        },
        'permission_callback' => function () {
            return current_user_can( 'edit_others_posts' );
        },
    ] );
} );

激活后到 wp-admin → Settings → MCP Adapter，你应该能在"Available Abilities"列表里看到 site-audit/find-broken-links。

Step 3：生成 Application Password

到 wp-admin → Users → Profile → Application Passwords，名字填 Claude Code MCP，点 Add。**复制生成的 24 位密码**——页面刷新后这个密码就再也看不到完整版本了。

权限控制：MCP Adapter 默认用 Application Password 关联的用户做权限检查，**editor 及以上角色**才能调用 site-audit/* 这类写操作 Abilities。如果你的 Claude 账号只是 author，能列文章但不能批量改 description。

Step 4：在 Claude Code 里接通

回到终端，用 claude mcp add-json 把这个 WP 站点注册成 Claude Code 的一个 MCP server：

claude mcp add-json wordpress-mcp \
  --scope user \
  '{"command":"php","args":["/var/www/html/wp-content/plugins/mcp-adapter/bin/mcp-adapter.php","serve","--server=mcp-adapter-default-server","--user=admin"],"env":{"WP_CLI_PHP_ARGS":"--no-header"}}'

> 注意：--user=admin 是 WordPress 内的 username（不是 display name），对应 Application Password 关联的账号。command 必须是绝对路径到 PHP CLI，否则 daemon 模式下 PATH 找不到。

注册完用 claude mcp list 验证：

$ claude mcp list
wordpress-mcp  ✓ connected  · 14 tools

启动 Claude Code 后直接问："扫描这个站点有哪些 broken link"——Claude 会自动调用 site-audit/find-broken-links Ability，不需要你手动写 prompt 引导。

💣 4 个真实踩坑与修复

坑 1：Abilities 检测不到（`Abilities=no`）

**症状**：wp eval 输出 Abilities=no，但你确定在 7.0 核心里。

**根因**：WordPress 7.0 的 Abilities API 是**模块化加载**的，必须有插件或主题显式调用 abilities_api_init action 才会触发注册。光在 functions.php 里写 wp_register_ability() 没用——它注册得太早，hook 还没挂上。

**修复**：把 wp_register_ability() 包装在 add_action( 'abilities_api_init', ... ) 里，并且确保插件**加载顺序在 mcp-adapter 之后**（插件 header 加 Requires Plugins: mcp-adapter）。

坑 2：Application Password 401 错配

**症状**：claude mcp list 显示 ✓ connected，但 Claude 一调用就报 401 Unauthorized。

**根因**：WordPress 7.0 的 Application Passwords 在 6.9 之后改为**对 REST API 路径有白名单**——只有 Authorization: Basic ... 出现在 wp-json/* 路径才会校验。MCP Adapter 的 transport 默认走自定义 endpoint /?mcp-adapter=1，**没走 REST 路由**，密码校验直接跳过。

**修复**：在 wp-config.php 加：

// 强制让所有 endpoint 都校验 Application Password
add_filter( 'application_password_is_api_request', '__return_true' );

或者在插件初始化时挂 'mcp_adapter.auth.use_application_passwords' => true filter。我选前者，少动插件。

坑 3：Streamable HTTP 跨域被浏览器拦截

**症状**：Claude Desktop 连接时报 CORS error: No 'Access-Control-Allow-Origin' header。命令行 Claude Code 没事，**只有 GUI 客户端**有问题。

**根因**：MCP 规范在 2025-Q4 把 SSE 标为 deprecated 后，新客户端默认用 streamable HTTP（即 chunked transfer 长期连接）。但 streamable HTTP 的 preflight OPTIONS 请求**不会被 WordPress 路由到 MCP Adapter**——WordPress 的 WP_Rewrite 不知道这个 endpoint。

**修复**：在 functions.php 或 mu-plugin 里手动挂 CORS header：

add_action( 'init', function () {
    if ( strpos( $_SERVER['REQUEST_URI'] ?? '', 'mcp-adapter' ) !== false ) {
        header( 'Access-Control-Allow-Origin: https://claude.ai' );
        header( 'Access-Control-Allow-Methods: GET, POST, OPTIONS' );
        header( 'Access-Control-Allow-Headers: Authorization, Content-Type, Mcp-Session-Id' );
        header( 'Access-Control-Max-Age: 86400' );
        if ( $_SERVER['REQUEST_METHOD'] === 'OPTIONS' ) {
            status_header( 204 );
            exit;
        }
    }
} );

> 注意 Access-Control-Allow-Origin 不要写 *——MCP 规范要求带 Authorization header 时不能用 wildcard。

坑 4：Abilities 命名冲突

**症状**：升级到 mcp-adapter 0.5.0 之后，Claude 调用时报 Tool 'wp.posts.list' already exists。

**根因**：mcp-adapter 0.5.0（2026-06 release）开始**自动注册 core Abilities**（wp.posts.list / wp.posts.get / wp.options.update 等 14 个），但你之前在 0.4.x 时代手动注册了同名的 wp.posts.list Ability。两个注册都在，CLI 启动时 mcp-adapter 不去重，server 起不来。

**修复**：删掉你自己注册的 wp.posts.list 等 core 默认 Abilities（用 core 的就行），只保留自定义的 site-audit/* 这类。命名空间用你自己的 prefix 隔开，能避免 99% 的冲突。

🛡️ 进阶：让 AI 真正能"改"东西

跑通 read-only Abilities 之后下一步是让 AI 写。我加了 1 个改 SEO description 的 Ability，给的 prompt 例子是：

"把本月发布但没设 SEO description 的文章补上 description，从正文第一段提取，不超过 160 字符。"

Claude Code 会自动拆 4 步：调用 wp.posts.list 过滤 → 调 wp.posts.get 读内容 → 调我自定义的 site-audit/generate-description → 调 wp.options.update 写入 Yoast/RankMath meta。**整条链路 12 秒**，人工操作要 5 分钟/篇。

安全控制（必做）：

1. **限制来源 IP**：在 Nginx 给 ?mcp-adapter=1 路径加 allow 白名单，只让本机 + Cloudflare Tunnel 段 IP 访问

2. **速率限制**：在 application_passwords filter 钩子里加 quota，每小时最多 200 次调用

3. **审计日志**：MCP Adapter 0.5.0 自带 observability 子系统，配置 mcp-adapter/log 写到 /var/log/mcp-adapter.log，每周轮转

总结与下一步

WordPress 7.0 + MCP Adapter + Abilities API + Claude Code 4 件套，把"AI 编辑 WordPress"从"复制粘贴 HTML 草稿"变成了"AI 直接调用站点能力"。3 个晚上的踩坑主要花在认证链（Application Password 校验路径）、transport 切换（SSE → streamable HTTP）、命名空间隔离三处。

下一步可写两个方向：

**WordPress 7.0 协作编辑实战**：7.0 新加的 default HTTP polling sync provider，**多人同时编辑文章**的冲突解决实测
**MCP 安全实战**：把 `mcp-adapter` 暴露面限制到 Cloudflare Tunnel 之后（接 6/17 那篇 Cloudflare Tunnel 零端口方案），实现"AI 客户端只能从指定 IP 段访问 MCP endpoint"

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

☁️ DigitalOcean Cloud ⚡ Vultr VPS ⭐ MiniMax Token Plan 🧩 Zhipu Coding Plan 🎁 Zhipu 20M Tokens Gift 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🔍 WordPress SEO Books 🌐 Web Hosting Books 🐳 Docker Books 🐧 Linux Books 🐍 Python Books 💰 Affiliate Marketing 💵 Passive Income Books 🖥️ Server Books ☁️ Cloud Computing Books 🚀 DevOps Books

← 返回首页