wordpress-mcp

Name: wordpress-mcp
Author: Automattic

作者：Automattic664 星标更新：2025-08-30

安装使用来源：spider==github.com

项目介绍

【技术文档摘要】：此仓库将被弃用，因为 mcp-adapter 的 AI 构建模块在 WordPress 中继续发布稳定版本。

这一变化与两个重要发展相一致：

Abilities API 已经在 WordPress 核心中作为版本 6.9 的一部分。
mcp-adapter 现已稳定，并将成为 WordPress 中 MCP 集成的标准插件和 Composer 包。

我们鼓励所有用户迁移到 mcp-adapter。未来的工作，包括新功能和修复，将在那里进行。此仓库将以存档形式保留，供历史参考。

WordPress MCP

这是一个全面的 WordPress 插件，实现了 Model Context Protocol (MCP)，通过标准化接口暴露 WordPress 功能。此插件使 AI 模型和应用程序能够通过多种传输协议和企业级身份验证安全地与 WordPress 站点交互。

功能

双传输协议：STDIO 和基于 HTTP 的（流式）传输
JWT 身份验证：具有管理界面的安全令牌身份验证
管理员界面：基于 React 的令牌管理和设置仪表板
AI 友好 API：符合 JSON-RPC 2.0 规范的端点用于 AI 集成
可扩展架构：支持自定义工具、资源和提示
WordPress 功能 API：适配标准化的 WordPress 功能
实验性 REST API CRUD 工具：适用于任何 WordPress REST API 端点的通用工具
全面测试：涵盖所有协议和身份验证的 200 多个测试用例
高性能：优化的路由和缓存机制
企业级安全性：多层身份验证和审计日志

架构

该插件实现了一个双传输架构：

WordPress MCP 插件
├── 传输层
│   ├── McpStdioTransport (/wp/v2/wpmcp)
│   └── McpStreamableTransport (/wp/v2/wpmcp/streamable)
├── 身份验证
│   └── JWT 身份验证系统
├── 方法处理器
│   ├── 工具、资源、提示
│   └── 系统及初始化
└── 管理员界面
    └── 基于 React 的令牌管理

传输协议

协议	端点	格式	身份验证	使用场景
STDIO	`/wp/v2/wpmcp`	WordPress 风格	JWT + 应用密码	兼容旧版
流式	`/wp/v2/wpmcp/streamable`	JSON-RPC 2.0	仅 JWT	现代 AI 客户端

安装

快速安装

从发布页面下载 wordpress-mcp.zip
上传到 /wp-content/plugins/wordpress-mcp 目录
通过 WordPress 管理菜单中的“插件”激活
导航到 设置 > WordPress MCP 进行配置

Composer 安装（开发）

cd wp-content/plugins/
git clone https://github.com/Automattic/wordpress-mcp.git
cd wordpress-mcp
composer install --no-dev
npm install && npm run build

身份验证设置

JWT 令牌生成

转到 设置 > WordPress MCP > 身份验证令牌
选择令牌有效期（1-24 小时）
点击“生成新令牌”
复制令牌以在您的 MCP 客户端中使用

MCP 客户端配置

使用 mcp-wordpress-remote 代理的 Claude Desktop 配置

添加到您的 Claude Desktop claude_desktop_config.json：

{
	"mcpServers": {
		"wordpress-mcp": {
			"command": "npx",
			"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
			"env": {
				"WP_API_URL": "https://your-site.com/",
				"JWT_TOKEN": "your-jwt-token-here",
				"LOG_FILE": "可选的日志文件路径"
			}
		}
	}
}

使用应用密码（替代方案）

{
	"mcpServers": {
		"wordpress-mcp": {
			"command": "npx",
			"args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ],
			"env": {
				"WP_API_URL": "https://your-site.com/",
				"WP_API_USERNAME": "your-username",
				"WP_API_PASSWORD": "your-application-password",
				"LOG_FILE": "可选的日志文件路径"
			}
		}
	}
}

使用直接流式传输的 VS Code MCP 扩展

添加到您的 VS Code MCP 设置：

{
	"servers": {
		"wordpress-mcp": {
			"type": "http",
			"url": "https://your-site.com/wp-json/wp/v2/wpmcp/streamable",
			"headers": {
				"Authorization": "Bearer your-jwt-token-here"
			}
		}
	}
}

MCP Inspector（开发/测试）

# 使用 JWT 令牌和代理
npx @modelcontextprotocol/inspector \
  -e WP_API_URL=https://your-site.com/ \
  -e JWT_TOKEN=your-jwt-token-here \
  npx @automattic/mcp-wordpress-remote@latest

# 使用应用密码和代理
npx @modelcontextprotocol/inspector \
  -e WP_API_URL=https://your-site.com/ \
  -e WP_API_USERNAME=your-username \
  -e WP_API_PASSWORD=your-application-password \
  npx @automattic/mcp-wordpress-remote@latest

本地开发配置

{
	"mcpServers": {
		"wordpress-local": {
			"command": "node",
			"args": [ "/path/to/mcp-wordpress-remote/dist/proxy.js" ],
			"env": {
				"WP_API_URL": "http://localhost:8080/",
				"JWT_TOKEN": "your-local-jwt-token",
				"LOG_FILE": "可选的日志文件路径"
			}
		}
	}
}

使用

与 MCP 客户端一起使用

此插件无缝地与两种方式兼容的 MCP 客户端一起工作：

通过代理：

mcp-wordpress-remote - 官方 MCP 客户端，具有增强的功能
配置了代理的 Claude Desktop，以支持完整的 WordPress 和 WooCommerce
使用 STDIO 传输协议的任何 MCP 客户端

直接流式传输：

直接连接到 /wp/v2/wpmcp/streamable 的 VS Code MCP 扩展
使用 JSON-RPC 2.0 的自定义 HTTP 基础 MCP 实现
支持 HTTP 传输和 JWT 身份验证的任何客户端

流式传输提供了一个直接的 JSON-RPC 2.0 兼容端点，而代理提供了额外的功能，如 WooCommerce 集成、增强的日志记录以及对旧版身份验证方法的支持。

可用的 MCP 方法

方法	描述	传输支持
`initialize`	初始化 MCP 会话	两者
`tools/list`	列出可用工具	两者
`tools/call`	执行一个工具	两者
`resources/list`	列出可用资源	两者
`resources/read`	读取资源内容	两者
`prompts/list`	列出可用提示	两者
`prompts/get`	获取提示模板	两者

实验性 REST API CRUD 工具

实验性功能：此功能是实验性的，可能会在未来版本中更改或删除。

启用 设置 > WordPress MCP > 启用 REST API CRUD 工具 后，插件提供了三个强大的通用工具，可以与任何 WordPress REST API 端点交互：

可用工具

工具名称	描述	类型
`list_api_functions`	发现所有可用的 WordPress REST API 端点	读取
`get_function_details`	获取特定端点/方法的详细元数据	读取
`run_api_function`	执行任何 REST API 函数并执行 CRUD 操作	操作

使用流程

发现：使用 list_api_functions 查看所有可用的端点
检查：使用 get_function_details 了解所需参数
执行：使用 run_api_function 执行 CRUD 操作

安全性和权限

用户能力：所有操作都尊重当前用户的权限
设置控制：可以在设置中禁用个别 CRUD 操作：
- 启用创建工具（POST 操作）
- 启用更新工具（PATCH/PUT 操作）
- 启用删除工具（DELETE 操作）
自动过滤：排除敏感端点（JWT 认证、oembed、自动保存、修订）

优点

通用访问：适用于任何 WordPress REST API 端点，包括自定义文章类型和第三方插件
AI 友好：为 AI 代理提供发现和内省功能
标准合规：使用标准的 HTTP 方法（GET、POST、PATCH、DELETE）
权限安全：继承 WordPress 用户能力并尊重端点权限

开发

项目结构

wp-content/plugins/wordpress-mcp/
├── includes/                   # PHP 类
│   ├── Core/                  # 传输和核心逻辑
│   ├── Auth/                  # JWT 身份验证
│   ├── Tools/                 # MCP 工具
│   ├── Resources/             # MCP 资源
│   ├── Prompts/               # MCP 提示
│   └── Admin/                 # 设置界面
├── src/                       # React 组件
│   └── settings/              # 管理员界面组件
├── tests/                     # 测试套件
│   └── phpunit/              # PHPUnit 测试
└── docs/                      # 文档

添加自定义工具

您可以通过自己的插件或主题来扩展 MCP 功能，添加自定义工具。在您的插件或主题中创建一个新的工具类：

<?php
declare(strict_types=1);

namespace Automattic\WordpressMcp\Tools;

class MyCustomTool {
    public function register(): void {
        add_action('wp_mcp_register_tools', [$this, 'register_tool']);
    }

    public function register_tool(): void {
        WPMCP()->register_tool([
            'name' => 'my_custom_tool',
            'description'  => '我的自定义工具描述',
            'inputSchema' => [
                'type' => 'object',
                'properties' => [
                    'param1' => ['type' => 'string', 'description' => '参数 1']
                ],
                'required' => ['param1']
            ],
            'callback' => [$this, 'execute'],
        ]);
    }

    public function execute(array $args): array {
        // 您的工具逻辑在这里
        return ['result' => 'success'];
    }
}

添加自定义资源

您可以通过自己的插件或主题来扩展 MCP 功能，添加自定义资源。在您的插件或主题中创建一个新的资源类：

<?php
declare(strict_types=1);

namespace Automattic\WordpressMcp\Resources;

class MyCustomResource {
    public function register(): void {
        add_action('wp_mcp_register_resources', [$this, 'register_resource']);
    }

    public function register_resource(): void {
        WPMCP()->register_resource([
            'uri' => 'custom://my-resource',
            'name' => '我的自定义资源',
            'description' => '自定义资源描述',
            'mimeType' => 'application/json',
            'callback' => [$this, 'get_content'],
        ]);
    }

    public function get_content(): array {
        return ['contents' => [/* 资源数据 */]];
    }
}

测试

运行全面的测试套件：

# 运行所有测试
vendor/bin/phpunit

# 运行特定的测试套件
vendor/bin/phpunit tests/phpunit/McpStdioTransportTest.php
vendor/bin/phpunit tests/phpunit/McpStreamableTransportTest.php
vendor/bin/phpunit tests/phpunit/JwtAuthTest.php

# 运行带有覆盖率报告
vendor/bin/phpunit --coverage-html coverage/

构建前端

# 开发构建
npm run dev

# 生产构建
npm run build

# 监视模式
npm run start

安全

最佳实践

令牌管理：使用最短的有效期时间（1-24 小时）
用户权限：令牌继承用户能力
安全存储：永远不要将令牌提交到仓库
定期清理：及时撤销未使用的令牌
访问控制：流式传输需要管理员权限
CRUD 操作：仅在必要时启用创建/更新/删除工具
实验性功能：在生产环境中谨慎使用 REST API CRUD 工具

安全特性

JWT 签名验证
令牌过期和撤销
用户能力继承
安全密钥生成
安全事件审计日志
防护畸形请求

测试覆盖

插件包括广泛的测试：

传输测试：STDIO 和流式传输协议
身份验证测试：JWT 生成、验证和撤销
集成测试：跨传输比较
安全测试：边缘案例和畸形请求
性能测试：负载和压力测试

查看详细的测试文档在 tests/README.md。

配置

环境变量

// wp-config.php
define('WPMCP_JWT_SECRET_KEY', 'your-secret-key');
define('WPMCP_DEBUG', true); // 启用调试日志

插件设置

通过 设置 > WordPress MCP 访问：

启用/禁用 MCP：切换插件功能
传输配置：配置 STDIO/流式传输
功能开关：启用/禁用特定工具和资源
CRUD 操作控制：对创建、更新和删除操作的细粒度控制
实验性功能：启用 REST API CRUD 工具（实验性功能）
身份验证设置：JWT 令牌管理

CRUD 操作设置

插件提供了对 CRUD 操作的细粒度控制：

启用创建工具：允许通过 MCP 工具进行 POST 操作
启用更新工具：允许通过 MCP 工具进行 PATCH/PUT 操作
启用删除工具：⚠️ 允许通过 MCP 工具进行 DELETE 操作（谨慎使用）
启用 REST API CRUD 工具：🧪 启用实验性的通用 REST API 访问工具

安全提示：删除操作可以永久移除数据。仅在信任所有 MCP 访问用户的情况下启用删除工具。

贡献

我们欢迎贡献！请参阅我们的贡献指南。

开发设置

克隆仓库
运行 composer install 安装 PHP 依赖
运行 npm install 安装 JavaScript 依赖
设置 WordPress 测试环境
使用 vendor/bin/phpunit 运行测试

文档

文档概述：docs/README.md
客户端设置指南：docs/client-setup.md
AI 集成指南：docs/for-ai.md
注册工具：docs/registered-tools.md
注册资源：docs/registered-resources.md
注册提示：docs/registered-prompts.md
注册 MCP 工具：docs/register-mcp-tools.md
注册 MCP 提示：docs/register-mcp-prompt.md
注册 MCP 资源：docs/register-mcp-resources.md
故障排除指南：docs/troubleshooting.md
测试指南：tests/README.md

支持

对于支持和问题：

文档：docs/README.md
错误报告：[GitHub Issues](https://github.com/A