Local by Flywheel

MCP Server Local WP

🎯 What if your AI assistant could actually SEE your WordPress database?

A Model Context Protocol (MCP) server that gives AI assistants like Claude and Cursor direct, read-only access to your Local by Flywheel WordPress database. No more guessing table structures. No more writing SQL queries blind. Your AI can now understand your actual data.

🤔 What's an MCP Server?

Think of MCP (Model Context Protocol) as a secure bridge between AI assistants and your development tools. Instead of copying and pasting database schemas or query results, MCP servers let AI assistants directly interact with your tools while you maintain complete control.

Without MCP: "Hey AI, I think there's a table called wp_something with a column that might be named user_meta... can you write a query?"
With MCP: "Hey AI, check what's in my database and write the exact query I need."

💡 The WordPress Developer's Dilemma

Picture this: You're debugging a LearnDash integration issue. Quiz results aren't syncing properly. You fire up Cursor to help diagnose the problem, but without database access, even the most advanced AI is just making educated guesses about your table structures.

The Real-World Impact

Here's an actual support ticket we were working on. The task was simple: fetch quiz activity data from LearnDash tables.

❌ Before MCP Server (AI Flying Blind):

The AI tried its best, suggesting this query:

$quiz_activities = $wpdb->get_results( 
  $wpdb->prepare( 
    'SELECT post_id, activity_meta FROM ' . esc_sql( LDLMS_DB::get_table_name( 'user_activity' ) ) . ' 
     WHERE user_id=%d AND activity_type=%s AND activity_status=1 AND activity_completed IS NOT NULL',
    $user_id, 
    'quiz' 
  ), 
  ARRAY_A 
);

Problem? The activity_meta column doesn't exist! LearnDash stores metadata in a completely separate table with a different structure. Without database access, the AI made reasonable but incorrect assumptions. You'd spend the next 20 minutes manually correcting table names, discovering relationships, and rewriting the query.

✅ After MCP Server (AI With X-Ray Vision):

With database access, the AI immediately saw the actual table structure and wrote:

$quiz_activities = $wpdb->get_results(
  $wpdb->prepare(
    'SELECT ua.post_id, ua.activity_id, uam.activity_meta_key, uam.activity_meta_value 
     FROM ' . esc_sql( LDLMS_DB::get_table_name( 'user_activity' ) ) . ' ua
     LEFT JOIN ' . esc_sql( LDLMS_DB::get_table_name( 'user_activity_meta' ) ) . ' uam 
     ON ua.activity_id = uam.activity_id 
     WHERE ua.user_id=%d AND ua.activity_type=%s AND ua.activity_completed IS NOT NULL
     AND uam.activity_meta_key IN (%s, %s, %s)',
    $user_id,
    'quiz',
    'percentage',
    'points',
    'total_points'
  ),
  ARRAY_A
);

The difference? The AI could see that metadata lives in a separate user_activity_meta table, understood the relationship through activity_id, and knew exactly which meta keys were available. First try. Zero guesswork. Problem solved.

🚀 Why This Changes Everything

When your AI assistant can read your database:

• No more schema guessing - It sees your actual tables and columns
• Accurate JOIN operations - It understands table relationships
• Real data validation - It can verify that data exists before suggesting queries
• Plugin-aware development - It adapts to any plugin's custom tables (WooCommerce, LearnDash, etc.)
• Instant debugging - "Show me all users who haven't completed quiz ID 42" becomes a 5-second task

🔧 The Local by Flywheel Challenge We Solved

When using the original mcp-server-mysql with Local by Flywheel, developers face several challenges:

1. Dynamic Paths: Local by Flywheel generates unique identifiers for each site (like lx97vbzE7) that change when sites are restarted
2. Socket vs Port Confusion: Local uses both Unix sockets and TCP ports, but the configuration can be tricky
3. Hardcoded Configurations: Most setups require manual path updates every time Local restarts

Our Solution

This MCP server automatically detects your active Local by Flywheel MySQL instance by:

1. Process Detection: Scans running processes to find active mysqld instances
2. Config Parsing: Extracts MySQL configuration from the active Local site
3. Dynamic Connection: Connects using the correct socket path or port automatically
4. Fallback Support: Falls back to environment variables for non-Local setups

Multi-Site Support

When you have multiple Local sites, the server uses priority-based site selection to ensure you're always connected to the right database:

Selection Priority

1. SITE_ID env var - Direct site ID (highest priority)
2. SITE_NAME env var - Human-readable site name lookup
3. Working directory detection - If your cwd is within a Local site path, that site is used
4. Process detection - First running Local mysqld found
5. Filesystem fallback - Most recently modified socket

Explicit Site Selection

Specify which site to connect to in your MCP config:

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

Or use the site ID directly:

{
  "env": {
    "SITE_ID": "lx97vbzE7"
  }
}

Working Directory Detection

When using Claude Code or Cursor, the server automatically detects which site you're working in based on your current directory. If you're editing files in /Users/.../Local Sites/dev/app/public/wp-content/plugins/my-plugin/, the server connects to the "dev" site's database automatically.

Verifying Your Connection

Use the mysql_current_site tool to see which site you're connected to:

{
  "siteName": "dev",
  "siteId": "lx97vbzE7",
  "sitePath": "/Users/.../Local Sites/dev",
  "domain": "dev.local",
  "selectionMethod": "cwd_detection"
}

Use mysql_list_sites to see all available sites and their status.

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

mysql_current_site

Get information about the currently connected Local WordPress site.

Returns the site name, ID, path, domain, socket path, and how the site was selected (env var, cwd detection, or auto-detection).

{
  "tool": "mysql_current_site",
  "args": {}
}
// Returns:
// {
//   "siteName": "dev",
//   "siteId": "lx97vbzE7",
//   "sitePath": "/Users/.../Local Sites/dev",
//   "domain": "dev.local",
//   "selectionMethod": "cwd_detection",
//   "socketPath": "/Users/.../Local/run/lx97vbzE7/mysql/mysqld.sock"
// }

mysql_list_sites

List all available Local WordPress sites and their running status.

{
  "tool": "mysql_list_sites",
  "args": {}
}
// Returns:
// {
//   "sites": [
//     { "id": "lx97vbzE7", "name": "dev", "domain": "dev.local", "running": true },
//     { "id": "WP7lolWDi", "name": "staging", "domain": "staging.local", "running": false }
//   ],
//   "currentSiteId": "lx97vbzE7"
// }

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-w

---

*README truncated. [View full README on GitHub](https://github.com/verygoodplugins/mcp-local-wp).*