MCP Local Wp

🚀 MCP Server Local WP

Enable AI assistants like Claude and Cursor to directly access your Local by Flywheel WordPress database in a read - only manner, eliminating schema guessing and enabling accurate query generation.

🚀 Quick Start

This MCP server allows AI assistants such as Claude and Cursor to directly access your Local by Flywheel WordPress database in a read - only mode. It simplifies the process of interacting with the database, enabling your AI to understand your actual data without the need for manual SQL query writing.

✨ Features

• Direct Database Access: Grants AI assistants direct read - only access to your Local by Flywheel WordPress database.
• Eliminates Schema Guessing: AI can see actual tables and columns, avoiding the need to guess database schemas.
• Accurate JOIN Operations: Understands table relationships for precise JOIN operations.
• Real Data Validation: Verifies data existence before suggesting queries.
• Plugin - Aware Development: Adapts to custom tables of various plugins like WooCommerce and LearnDash.
• Instant Debugging: Speeds up debugging tasks, such as quickly retrieving specific user data.
• Automatic Detection: Automatically detects the active Local by Flywheel MySQL instance.

📦 Installation

Prerequisites

• Local by Flywheel installed and running.
• An active Local site running.
• Node.js 18+ (for local development only).

Quick Setup (Recommended)

The easiest way to get started - no installation required:

Cursor IDE Configuration

Add this to your Cursor MCP configuration file (.cursor/mcp.json):

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

Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

• 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"
      ]
    }
  }
}

Advanced Setup (Local Development)

For customization or local development:

Install from Source

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

Local Configuration

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

Custom Environment Variables

For non - Local setups or custom configurations:

{
  "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"
      }
    }
  }
}

💻 Usage Examples

Basic Usage

Once connected, you can use the mysql_query tool to execute any SQL query against your Local WordPress database.

-- Getting Recent Posts
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;

Advanced Usage

-- Exploring Database Structure
-- See all tables
SHOW TABLES;

-- Examine a table structure
DESCRIBE wp_posts;

-- Get table info
SHOW TABLE STATUS LIKE 'wp_%';

-- WordPress - Specific Queries
-- Get site options
SELECT option_name, option_value 
FROM wp_options 
WHERE option_name IN ('blogname', 'blogdescription', 'admin_email');

-- Find active plugins
SELECT option_value 
FROM wp_options 
WHERE option_name = 'active_plugins';

-- Get user information
SELECT user_login, user_email, display_name 
FROM wp_users 
LIMIT 10;

-- Post meta data
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';

📚 Documentation

Tools Available

mysql_query

Execute read - only SQL against your Local WordPress database.

Input fields:

• sql (string): Single read - only statement (SELECT/SHOW/DESCRIBE/EXPLAIN).
• params (string[]): Optional parameter values for ? placeholders.

Example Usage:

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

-- Direct queries
SELECT option_name, option_value FROM wp_options WHERE option_name LIKE '%theme%';
SHOW TABLES;
DESCRIBE wp_users;

mysql_schema

Inspect database schema using INFORMATION_SCHEMA.

• No args: lists tables with basic stats.
• With table: returns columns and indexes for that table.

Examples:

// List all tables
{
  "tool": "mysql_schema",
  "args": {}
}

// Inspect a specific table
{
  "tool": "mysql_schema",
  "args": { "table": "wp_posts" }
}

How It Works with Local by Flywheel

This MCP server was created to solve the difficulties of connecting to Local by Flywheel MySQL with existing MCP servers.

The Original Problem

When using the original [mcp - server - mysql](https://github.com/benborla/mcp - server - mysql) with Local by Flywheel, developers faced several challenges:

1. Dynamic Socket Paths: Local generates paths like /Users/.../Local/run/lx97vbzE7/mysql/mysqld.sock where lx97vbzE7 changes each time you restart Local.
2. Configuration Complexity: The original server required hardcoded paths that would break every time Local restarted.
3. Host/Port Confusion: Local's MySQL configuration can be tricky with both socket and TCP connections available.

Our Solution Process

We solved this step by step:

1. Process - Based Detection

Instead of guessing paths, we scan for the actual running MySQL process:

ps aux | grep mysqld | grep -v grep

This finds the active MySQL instance and extracts its configuration file path.

2. Dynamic Path Resolution

// From the process args: --defaults - file=/Users/.../Local/run/lx97vbzE7/conf/mysql/my.cnf
// We extract the site directory and build the socket path
const configPath = extractFromProcess();
const siteDir = path.dirname(path.dirname(path.dirname(configPath)));
const socketPath = path.join(siteDir, 'mysql/mysqld.sock');

3. Automatic Configuration

The server automatically configures itself with:

• Correct socket path for the active Local site.
• Proper database name (local).
• Default credentials (root/root).
• Fallback to environment variables if needed.

Why This Approach Works

• Restart Resilient: Works every time you restart Local by Flywheel.
• Site Switching: Automatically adapts if you switch between Local sites.
• Zero Maintenance: No need to manually update paths ever again.
• Error Handling: Provides clear error messages if MySQL isn't running.

Local Directory Structure We Handle

~/Library/Application Support/Local/run/
├── lx97vbzE7/                    # Dynamic site ID (changes on restart)
│   ├── conf/mysql/my.cnf        # We read this for port info
│   └── mysql/mysqld.sock        # We connect via this socket
└── WP7lolWDi/                   # Another site (if multiple running)
    ├── conf/mysql/my.cnf
    └── mysql/mysqld.sock

The server intelligently finds the active site and connects to the right MySQL instance.

🔧 Technical Details

When using the MCP server with Local by Flywheel, it first detects the running mysqld process. By analyzing the process arguments, it extracts the configuration file path. Then, it calculates the socket path based on the configuration file path. The server automatically configures the connection parameters, including the socket path, database name, and credentials. In case of non - Local setups, it can fall back to environment variables.

📄 License

GPL - 3.0 - or - later - see the LICENSE file for details. As a WordPress - focused tool, we embrace the copyleft philosophy to ensure this remains free and open for the community.

Troubleshooting

Common Issues

1. "No active MySQL process found"
   • Ensure Local by Flywheel is running.
   • Make sure at least one site is started in Local.
   • Check that the site's database is running.
2. "MySQL socket not found"
   • Verify the Local site is fully started.
   • Try stopping and restarting the site in Local.
   • Check Local's logs for MySQL startup issues.
3. Connection refused
   • Ensure the Local site's MySQL service is running.
   • Check if another process is using the MySQL port.
   • Try restarting Local by Flywheel.
4. Permission denied
   • Make sure the MySQL socket file has correct permissions.
   • Check if your user has access to Local's directories.

Manual Configuration

If auto - detection fails, you can manually configure the connection:

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

Debugging

Enable debug logging by setting DEBUG:

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

Security

• Read - only operations: Only SELECT/SHOW/DESCRIBE/EXPLAIN are allowed.
• Single statement: Multiple statements in one call are blocked.
• Local development: Designed for local environments (Local by Flywheel).
• No external connections: Prioritizes Unix socket connections when available.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/your - feature - name.
3. Make your changes and add tests.
4. Ensure TypeScript compiles: npm run build.
5. Submit a pull request.

Support

• GitHub Issues: [Report bugs or request features](https://github.com/verygoodplugins/mcp - local - wp/issues).
• Documentation: This README and inline code documentation.
• Community: Join the Model Context Protocol community discussions.

Related Projects

• [mcp - server - mysql](https://github.com/benborla/mcp - server - mysql) - The original MySQL MCP server that inspired this WordPress - specific version.
• Local by Flywheel - The local WordPress development environment this server is designed for.
• Model Context Protocol - The protocol specification.

Built with 🧡 by Jack Arturo at [Very Good Plugins](https://verygoodplugins.com?utm_source=github&utm_medium=readme&utm_campaign=mcp - local - wp) · Made with love for the open - source community