MCP Local Wp

🚀 MCP Server Local WP

MCP Server Local WP 是一个基于 Model Context Protocol (MCP) 的服务器，它能让 Claude 和 Cursor 等 AI 助手直接以只读方式访问你通过 Local by Flywheel 创建的 WordPress 数据库。有了它，AI 无需再猜测表结构，也不用盲目编写 SQL 查询，就能直接理解你的实际数据。

🚀 快速开始

前提条件

• 安装并运行 Local by Flywheel。
• 有一个正在运行的 Local 站点。
• 若进行本地开发，需安装 Node.js 18+。

快速设置（推荐）

Cursor IDE 配置

将以下内容添加到你的 Cursor MCP 配置文件（.cursor/mcp.json）中：

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-local-wp@latest"
      ]
    }
  }
}

Claude Desktop 配置

在 macOS 系统中，将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json 文件中；在 Windows 系统中，添加到 %APPDATA%\\Claude\\claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-local-wp@latest"
      ]
    }
  }
}

高级设置（本地开发）

从源码安装

git clone https://github.com/verygoodplugins/mcp-local-wp.git
cd mcp-local-wp
npm install
npm run build

本地配置

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "node",
      "args": [
        "/full/path/to/mcp-local-wp/dist/index.js"
      ]
    }
  }
}

自定义环境变量

对于非 Local 设置或自定义配置，可使用以下配置：

{
  "mcpServers": {
    "mcp-local-wp": {
      "command": "npx",
      "args": [
        "-y",
        "@verygoodplugins/mcp-local-wp@latest"
      ],
      "env": {
        "MYSQL_DB": "local",
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "root",
        "MYSQL_PASS": "root"
      }
    }
  }
}

✨ 主要特性

• 无需猜测表结构：AI 助手可以直接查看实际的表和列。
• 准确的 JOIN 操作：理解表之间的关系。
• 真实数据验证：在建议查询之前可以验证数据是否存在。
• 支持插件开发：能够适应任何插件的自定义表（如 WooCommerce、LearnDash 等）。
• 即时调试：例如，“显示所有未完成问卷 ID 42 的用户”这样的任务可以在几秒钟内完成。

💻 使用示例

基础用法

获取最近发布的文章：

SELECT ID, post_title, post_date, post_status 
FROM wp_posts 
WHERE post_type = 'post' AND post_status = 'publish' 
ORDER BY post_date DESC 
LIMIT 5;

高级用法

探索数据库结构

-- 查看所有表
SHOW TABLES;

-- 检查表结构
DESCRIBE wp_posts;

-- 获取表信息
SHOW TABLE STATUS LIKE 'wp_%';

WordPress 特定查询

-- 获取网站选项
SELECT option_name, option_value 
FROM wp_options 
WHERE option_name IN ('blogname', 'blogdescription', 'admin_email');

-- 查找激活的插件
SELECT option_value 
FROM wp_options 
WHERE option_name = 'active_plugins';

-- 获取用户信息
SELECT user_login, user_email, display_name 
FROM wp_users 
LIMIT 10;

-- 文章元数据
SELECT p.post_title, pm.meta_key, pm.meta_value
FROM wp_posts p
JOIN wp_postmeta pm ON p.ID = pm.post_id
WHERE p.post_type = 'post' AND pm.meta_key = '_edit_last';

🔧 技术细节

解决的 Local by Flywheel 挑战

使用原始的 mcp-server-mysql 与 Local by Flywheel 时，开发者会遇到以下挑战：

1. 动态路径：Local by Flywheel 为每个站点生成唯一标识符（如 lx97vbzE7），当站点重启时这些标识符会改变。
2. 套接字与端口混淆：Local 同时使用 Unix 套接字和 TCP 端口，但配置可能会很棘手。
3. 硬编码配置：大多数设置需要在 Local 每次重启时手动更新路径。

解决方案

这个 MCP 服务器通过以下方式自动检测你正在运行的 Local by Flywheel MySQL 实例：

1. 进程检测：扫描正在运行的进程以查找活动的 mysqld 实例。
2. 配置解析：从活动的 Local 站点中提取 MySQL 配置。
3. 动态连接：自动使用正确的套接字路径或端口进行连接。
4. 备用支持：对于非 Local 设置，回退到环境变量。

可用工具

mysql_query

对本地 WordPress 数据库执行只读 SQL 查询。 输入字段：

• sql（字符串）：单个只读语句（SELECT/SHOW/DESCRIBE/EXPLAIN）
• params（字符串数组）：? 占位符的可选参数值

示例用法：

-- 带参数
SELECT * FROM wp_posts WHERE post_status = ? ORDER BY post_date DESC LIMIT ?;
-- params: ["publish", "5"]

-- 直接查询
SELECT option_name, option_value FROM wp_options WHERE option_name LIKE '%theme%';
SHOW TABLES;
DESCRIBE wp_users;

mysql_schema

使用 INFORMATION_SCHEMA 检查数据库架构。

• 无参数：列出具有基本统计信息的表
• 带 table 参数：返回该表的列和索引

示例：

// 列出所有表
{
  "tool": "mysql_schema",
  "args": {}
}

// 检查特定表
{
  "tool": "mysql_schema",
  "args": { "table": "wp_posts" }
}

工作原理

原始问题

当首次尝试使用 mcp-server-mysql 与 Local by Flywheel 时，遇到了以下问题：

1. 动态套接字路径：Local 生成的路径（如 /Users/.../Local/run/lx97vbzE7/mysql/mysqld.sock）中的 lx97vbzE7 每次重启 Local 时都会改变。
2. 配置复杂性：原始服务器需要硬编码路径，每次 Local 重启时都会失效。
3. 主机/端口混淆：Local 的 MySQL 配置在套接字和 TCP 连接方面可能会很棘手。

解决方案流程

1. 基于进程的检测：

ps aux | grep mysqld | grep -v grep

通过此命令查找活动的 MySQL 实例并提取其配置文件路径。

2. 动态路径解析：

// 从进程参数中：--defaults-file=/Users/.../Local/run/lx97vbzE7/conf/mysql/my.cnf
// 提取站点目录并构建套接字路径
const configPath = extractFromProcess();
const siteDir = path.dirname(path.dirname(path.dirname(configPath)));
const socketPath = path.join(siteDir, 'mysql/mysqld.sock');

3. 自动配置： 服务器自动进行以下配置：

• 为活动的 Local 站点使用正确的套接字路径。
• 使用正确的数据库名称（local）。
• 使用默认凭据（root/root）。
• 必要时回退到环境变量。

优势

• 重启无忧：每次重启 Local by Flywheel 时都能正常工作。
• 站点切换：在切换 Local 站点时自动适应。
• 零维护：无需再手动更新路径。
• 错误处理：如果 MySQL 未运行，会提供清晰的错误消息。

处理的本地目录结构

~/Library/Application Support/Local/run/
├── lx97vbzE7/                    # 动态站点 ID（重启时更改）
│   ├── conf/mysql/my.cnf        # 读取此文件获取端口信息
│   └── mysql/mysqld.sock        # 通过此套接字连接
└── WP7lolWDi/                   # 另一个站点（如果有多个正在运行）
    ├── conf/mysql/my.cnf
    └── mysql/mysqld.sock

服务器会智能地找到活动站点并连接到正确的 MySQL 实例。

📄 许可证

本项目采用 GPL-3.0-or-later 许可证，详情请参阅 LICENSE 文件。作为一个专注于 WordPress 的工具，我们秉持 copyleft 理念，确保其对社区免费开放。

🔧 开发设置

从源码运行

1. 启动 Local 站点：确保有一个正在运行的 Local by Flywheel 站点。
2. 克隆并构建：

git clone https://github.com/verygoodplugins/mcp-local-wp.git
cd mcp-local-wp
npm install
npm run build

3. 测试连接：

node dist/index.js

开发模式

npm run dev

此命令会以 TypeScript 模式运行服务器，并监视更改。

代码检查与格式化

• 代码检查：npm run lint
• 修复代码检查问题：npm run lint:fix
• 格式化代码：npm run format
• 检查代码格式：npm run format:check

通过 ESLint + Prettier 统一 MCP 服务器的标准。

🔍 故障排除

常见问题

1. “未找到活动的 MySQL 进程”

   • 确保 Local by Flywheel 正在运行。
   • 确保 Local 中至少有一个站点已启动。
   • 检查站点的数据库是否正在运行。

2. “未找到 MySQL 套接字”

   • 验证 Local 站点已完全启动。
   • 尝试在 Local 中停止并重新启动站点。
   • 检查 Local 的日志以查看 MySQL 启动问题。

3. 连接被拒绝

   • 确保 Local 站点的 MySQL 服务正在运行。
   • 检查是否有其他进程正在使用 MySQL 端口。
   • 尝试重启 Local by Flywheel。

4. 权限被拒绝

   • 确保 MySQL 套接字文件具有正确的权限。
   • 检查你的用户是否有权限访问 Local 的目录。

手动配置

如果自动检测失败，你可以手动配置连接：

export MYSQL_SOCKET_PATH="/path/to/your/local/site/mysql/mysqld.sock"
export MYSQL_DB="local"
export MYSQL_USER="root"
export MYSQL_PASS="root"

调试

通过设置 DEBUG 启用调试日志：

DEBUG=mcp-local-wp mcp-local-wp

🔒 安全

• 只读操作：仅允许 SELECT/SHOW/DESCRIBE/EXPLAIN 操作。
• 单语句：阻止在一次调用中执行多个语句。
• 本地开发：专为本地环境（Local by Flywheel）设计。
• 无外部连接：在可用时优先使用 Unix 套接字连接。

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

开发指南

1. 分叉仓库。
2. 创建功能分支：git checkout -b feature/your-feature-name。
3. 进行更改并添加测试。
4. 确保 TypeScript 编译通过：npm run build。
5. 提交拉取请求。

📞 支持

• GitHub 问题：报告错误或请求功能
• 文档：本 README 和内联代码文档
• 社区：加入 Model Context Protocol 社区讨论

📚 相关项目

• mcp-server-mysql - 启发此 WordPress 特定版本的原始 MySQL MCP 服务器
• Local by Flywheel - 此服务器设计用于的本地 WordPress 开发环境
• Model Context Protocol - 协议规范

由 Jack Arturo 在 Very Good Plugins 用 ❤️ 构建 · 为开源社区精心打造