{"id":40639827,"url":"https://github.com/verygoodplugins/mcp-local-wp","last_synced_at":"2026-01-21T08:02:01.605Z","repository":{"id":313905652,"uuid":"1053101857","full_name":"verygoodplugins/mcp-local-wp","owner":"verygoodplugins","description":"MCP server for WordPress database access via Local by Flywheel","archived":false,"fork":false,"pushed_at":"2025-09-09T12:10:37.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T06:23:22.820Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/verygoodplugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T01:58:07.000Z","updated_at":"2025-09-09T22:39:06.000Z","dependencies_parsed_at":"2025-09-09T14:12:05.722Z","dependency_job_id":"2f85f2ef-e45c-46be-8e1f-ca4911624d90","html_url":"https://github.com/verygoodplugins/mcp-local-wp","commit_stats":null,"previous_names":["verygoodplugins/mcp-local-wp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/verygoodplugins/mcp-local-wp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-local-wp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-local-wp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-local-wp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-local-wp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/verygoodplugins","download_url":"https://codeload.github.com/verygoodplugins/mcp-local-wp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/verygoodplugins%2Fmcp-local-wp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28629922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-21T08:02:00.060Z","updated_at":"2026-01-21T08:02:01.599Z","avatar_url":"https://github.com/verygoodplugins.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Server Local WP\n\n**🎯 What if your AI assistant could actually SEE your WordPress database?**\n\nA 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.\n\n## 🤔 What's an MCP Server?\n\nThink 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.\n\n**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?\"  \n**With MCP**: \"Hey AI, check what's in my database and write the exact query I need.\"\n\n## 💡 The WordPress Developer's Dilemma\n\nPicture 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.\n\n### The Real-World Impact\n\nHere's an actual support ticket we were working on. The task was simple: fetch quiz activity data from LearnDash tables.\n\n**❌ Before MCP Server (AI Flying Blind):**\n\n![Very Good Plugins  Cursor+Diagnose LearnDash quiz field syncing issue — wp-fusion (Workspace)  2025-09-09 at 12 34 38](https://github.com/user-attachments/assets/65da669d-8515-49ed-942c-0dd43aa29bae)\n\nThe AI tried its best, suggesting this query:\n```php\n$quiz_activities = $wpdb-\u003eget_results( \n  $wpdb-\u003eprepare( \n    'SELECT post_id, activity_meta FROM ' . esc_sql( LDLMS_DB::get_table_name( 'user_activity' ) ) . ' \n     WHERE user_id=%d AND activity_type=%s AND activity_status=1 AND activity_completed IS NOT NULL',\n    $user_id, \n    'quiz' \n  ), \n  ARRAY_A \n);\n```\n\n**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.\n\n**✅ After MCP Server (AI With X-Ray Vision):**\n\n![Very Good Plugins  Cursor+Diagnose LearnDash quiz field syncing issue — wp-fusion (Workspace)  2025-09-09 at 12 54 07](https://github.com/user-attachments/assets/d266d9a4-a098-4ce5-9564-0db5f8e160bd)\n\nWith database access, the AI immediately saw the actual table structure and wrote:\n```php\n$quiz_activities = $wpdb-\u003eget_results(\n  $wpdb-\u003eprepare(\n    'SELECT ua.post_id, ua.activity_id, uam.activity_meta_key, uam.activity_meta_value \n     FROM ' . esc_sql( LDLMS_DB::get_table_name( 'user_activity' ) ) . ' ua\n     LEFT JOIN ' . esc_sql( LDLMS_DB::get_table_name( 'user_activity_meta' ) ) . ' uam \n     ON ua.activity_id = uam.activity_id \n     WHERE ua.user_id=%d AND ua.activity_type=%s AND ua.activity_completed IS NOT NULL\n     AND uam.activity_meta_key IN (%s, %s, %s)',\n    $user_id,\n    'quiz',\n    'percentage',\n    'points',\n    'total_points'\n  ),\n  ARRAY_A\n);\n```\n\n**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.\n\n## 🚀 Why This Changes Everything\n\nWhen your AI assistant can read your database:\n- **No more schema guessing** - It sees your actual tables and columns\n- **Accurate JOIN operations** - It understands table relationships\n- **Real data validation** - It can verify that data exists before suggesting queries\n- **Plugin-aware development** - It adapts to any plugin's custom tables (WooCommerce, LearnDash, etc.)\n- **Instant debugging** - \"Show me all users who haven't completed quiz ID 42\" becomes a 5-second task\n\n## 🔧 The Local by Flywheel Challenge We Solved\n\nWhen using the original [mcp-server-mysql](https://github.com/benborla/mcp-server-mysql) with Local by Flywheel, developers face several challenges:\n\n1. **Dynamic Paths**: Local by Flywheel generates unique identifiers for each site (like `lx97vbzE7`) that change when sites are restarted\n2. **Socket vs Port Confusion**: Local uses both Unix sockets and TCP ports, but the configuration can be tricky\n3. **Hardcoded Configurations**: Most setups require manual path updates every time Local restarts\n## Our Solution\n\nThis MCP server **automatically detects** your active Local by Flywheel MySQL instance by:\n\n1. **Process Detection**: Scans running processes to find active `mysqld` instances\n2. **Config Parsing**: Extracts MySQL configuration from the active Local site\n3. **Dynamic Connection**: Connects using the correct socket path or port automatically\n4. **Fallback Support**: Falls back to environment variables for non-Local setups\n\n## Multi-Site Support\n\nWhen you have multiple Local sites, the server uses **priority-based site selection** to ensure you're always connected to the right database:\n\n### Selection Priority\n\n1. **`SITE_ID` env var** - Direct site ID (highest priority)\n2. **`SITE_NAME` env var** - Human-readable site name lookup\n3. **Working directory detection** - If your cwd is within a Local site path, that site is used\n4. **Process detection** - First running Local mysqld found\n5. **Filesystem fallback** - Most recently modified socket\n\n### Explicit Site Selection\n\nSpecify which site to connect to in your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"wordpress-dev\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@verygoodplugins/mcp-local-wp@latest\"],\n      \"env\": {\n        \"SITE_NAME\": \"dev\"\n      }\n    }\n  }\n}\n```\n\nOr use the site ID directly:\n\n```json\n{\n  \"env\": {\n    \"SITE_ID\": \"lx97vbzE7\"\n  }\n}\n```\n\n### Working Directory Detection\n\nWhen 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.\n\n### Verifying Your Connection\n\nUse the `mysql_current_site` tool to see which site you're connected to:\n\n```jsonc\n{\n  \"siteName\": \"dev\",\n  \"siteId\": \"lx97vbzE7\",\n  \"sitePath\": \"/Users/.../Local Sites/dev\",\n  \"domain\": \"dev.local\",\n  \"selectionMethod\": \"cwd_detection\"\n}\n```\n\nUse `mysql_list_sites` to see all available sites and their status.\n\n## Tools Available\n\n### mysql_query\nExecute read-only SQL against your Local WordPress database.\n\nInput fields:\n- `sql` (string): Single read-only statement (SELECT/SHOW/DESCRIBE/EXPLAIN)\n- `params` (string[]): Optional parameter values for `?` placeholders\n\n**Example Usage:**\n```sql\n-- With parameters\nSELECT * FROM wp_posts WHERE post_status = ? ORDER BY post_date DESC LIMIT ?;\n-- params: [\"publish\", \"5\"]\n\n-- Direct queries\nSELECT option_name, option_value FROM wp_options WHERE option_name LIKE '%theme%';\nSHOW TABLES;\nDESCRIBE wp_users;\n```\n\n### mysql_schema\nInspect database schema using INFORMATION_SCHEMA.\n\n- No args: lists tables with basic stats\n- With `table`: returns columns and indexes for that table\n\nExamples:\n\n```jsonc\n// List all tables\n{\n  \"tool\": \"mysql_schema\",\n  \"args\": {}\n}\n\n// Inspect a specific table\n{\n  \"tool\": \"mysql_schema\",\n  \"args\": { \"table\": \"wp_posts\" }\n}\n```\n\n### mysql_current_site\nGet information about the currently connected Local WordPress site.\n\nReturns the site name, ID, path, domain, socket path, and how the site was selected (env var, cwd detection, or auto-detection).\n\n```jsonc\n{\n  \"tool\": \"mysql_current_site\",\n  \"args\": {}\n}\n// Returns:\n// {\n//   \"siteName\": \"dev\",\n//   \"siteId\": \"lx97vbzE7\",\n//   \"sitePath\": \"/Users/.../Local Sites/dev\",\n//   \"domain\": \"dev.local\",\n//   \"selectionMethod\": \"cwd_detection\",\n//   \"socketPath\": \"/Users/.../Local/run/lx97vbzE7/mysql/mysqld.sock\"\n// }\n```\n\n### mysql_list_sites\nList all available Local WordPress sites and their running status.\n\n```jsonc\n{\n  \"tool\": \"mysql_list_sites\",\n  \"args\": {}\n}\n// Returns:\n// {\n//   \"sites\": [\n//     { \"id\": \"lx97vbzE7\", \"name\": \"dev\", \"domain\": \"dev.local\", \"running\": true },\n//     { \"id\": \"WP7lolWDi\", \"name\": \"staging\", \"domain\": \"staging.local\", \"running\": false }\n//   ],\n//   \"currentSiteId\": \"lx97vbzE7\"\n// }\n```\n\n## Installation\n\n### Prerequisites\n\n- [Local by Flywheel](https://localwp.com/) installed and running\n- An active Local site running\n- Node.js 18+ (for local development only)\n\n## Quick Setup (Recommended)\n\nThe easiest way to get started - no installation required:\n\n### Cursor IDE Configuration\n\nAdd this to your Cursor MCP configuration file (`.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-local-wp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@verygoodplugins/mcp-local-wp@latest\"\n      ]\n    }\n  }\n}\n```\n\n### Claude Desktop Configuration\n\nAdd this to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\\\Claude\\\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-local-wp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@verygoodplugins/mcp-local-wp@latest\"\n      ]\n    }\n  }\n}\n```\n\n## Advanced Setup (Local Development)\n\nFor customization or local development:\n\n### Install from Source\n\n```bash\ngit clone https://github.com/verygoodplugins/mcp-local-wp.git\ncd mcp-local-wp\nnpm install\nnpm run build\n```\n\n### Local Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-local-wp\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/full/path/to/mcp-local-wp/dist/index.js\"\n      ]\n    }\n  }\n}\n```\n\n### Custom Environment Variables\n\nFor non-Local setups or custom configurations:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-local-wp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@verygoodplugins/mcp-local-wp@latest\"\n      ],\n      \"env\": {\n        \"MYSQL_DB\": \"local\",\n        \"MYSQL_HOST\": \"localhost\",\n        \"MYSQL_PORT\": \"3306\",\n        \"MYSQL_USER\": \"root\",\n        \"MYSQL_PASS\": \"root\"\n      }\n    }\n  }\n}\n```\n\n### Site Selection Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `SITE_ID` | Explicit site ID (highest priority) | `lx97vbzE7` |\n| `SITE_NAME` | Site name for lookup | `dev` |\n| `LOCAL_SITES_JSON` | Override path to Local's sites.json | `/custom/path/sites.json` |\n| `LOCAL_RUN_DIR` | Override Local's run directory | `/custom/run/path` |\n\n## How It Works with Local by Flywheel\n\nThis MCP server was created because connecting to Local by Flywheel MySQL was **\"kind of difficult to get working\"** with existing MCP servers. Here's the story of what we solved:\n\n### The Original Problem\n\nWhen we first tried to use [mcp-server-mysql](https://github.com/benborla/mcp-server-mysql) with Local by Flywheel, we encountered several issues:\n\n1. **Dynamic Socket Paths**: Local generates paths like `/Users/.../Local/run/lx97vbzE7/mysql/mysqld.sock` where `lx97vbzE7` changes each time you restart Local\n2. **Configuration Complexity**: The original server required hardcoded paths that would break every time Local restarted\n3. **Host/Port Confusion**: Local's MySQL configuration can be tricky with both socket and TCP connections available\n\n### Our Solution Process\n\nWe solved this step by step:\n\n#### 1. Process-Based Detection\nInstead of guessing paths, we scan for the actual running MySQL process:\n\n```bash\nps aux | grep mysqld | grep -v grep\n```\n\nThis finds the active MySQL instance and extracts its configuration file path.\n\n#### 2. Dynamic Path Resolution\n```typescript\n// From the process args: --defaults-file=/Users/.../Local/run/lx97vbzE7/conf/mysql/my.cnf\n// We extract the site directory and build the socket path\nconst configPath = extractFromProcess();\nconst siteDir = path.dirname(path.dirname(path.dirname(configPath)));\nconst socketPath = path.join(siteDir, 'mysql/mysqld.sock');\n```\n\n#### 3. Automatic Configuration\nThe server automatically configures itself with:\n- Correct socket path for the active Local site\n- Proper database name (`local`)\n- Default credentials (`root`/`root`)\n- Fallback to environment variables if needed\n\n### Why This Approach Works\n\n✅ **Restart Resilient**: Works every time you restart Local by Flywheel  \n✅ **Site Switching**: Automatically adapts if you switch between Local sites  \n✅ **Zero Maintenance**: No need to manually update paths ever again  \n✅ **Error Handling**: Provides clear error messages if MySQL isn't running  \n\n### Local Directory Structure We Handle\n\n```\n~/Library/Application Support/Local/run/\n├── lx97vbzE7/                    # Dynamic site ID (changes on restart)\n│   ├── conf/mysql/my.cnf        # We read this for port info\n│   └── mysql/mysqld.sock        # We connect via this socket\n└── WP7lolWDi/                   # Another site (if multiple running)\n    ├── conf/mysql/my.cnf\n    └── mysql/mysqld.sock\n```\n\nThe server intelligently finds the active site and connects to the right MySQL instance.\n\n## Usage Examples\n\nOnce connected, you can use the `mysql_query` tool to execute any SQL query against your Local WordPress database:\n\n### Getting Recent Posts\n\n```sql\nSELECT ID, post_title, post_date, post_status \nFROM wp_posts \nWHERE post_type = 'post' AND post_status = 'publish' \nORDER BY post_date DESC \nLIMIT 5;\n```\n\n### Exploring Database Structure\n\n```sql\n-- See all tables\nSHOW TABLES;\n\n-- Examine a table structure\nDESCRIBE wp_posts;\n\n-- Get table info\nSHOW TABLE STATUS LIKE 'wp_%';\n```\n\n### WordPress-Specific Queries\n\n```sql\n-- Get site options\nSELECT option_name, option_value \nFROM wp_options \nWHERE option_name IN ('blogname', 'blogdescription', 'admin_email');\n\n-- Find active plugins\nSELECT option_value \nFROM wp_options \nWHERE option_name = 'active_plugins';\n\n-- Get user information\nSELECT user_login, user_email, display_name \nFROM wp_users \nLIMIT 10;\n\n-- Post meta data\nSELECT p.post_title, pm.meta_key, pm.meta_value\nFROM wp_posts p\nJOIN wp_postmeta pm ON p.ID = pm.post_id\nWHERE p.post_type = 'post' AND pm.meta_key = '_edit_last';\n```\n\n## Development Setup\n\n### Running from Source\n\n1. **Start a Local site**: Make sure you have an active Local by Flywheel site running\n2. **Clone and build**:\n   ```bash\n   git clone https://github.com/verygoodplugins/mcp-local-wp.git\n   cd mcp-local-wp\n   npm install\n   npm run build\n   ```\n\n3. **Test the connection**:\n   ```bash\n   node dist/index.js\n   ```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\nThis runs the server with TypeScript watching for changes.\n\n### Linting \u0026 Formatting\n\n- Lint: `npm run lint`\n- Fix lint: `npm run lint:fix`\n- Format: `npm run format`\n- Check formatting: `npm run format:check`\n\nStandards are unified across MCP servers via ESLint + Prettier.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"No active MySQL process found\"**\n   - Ensure Local by Flywheel is running\n   - Make sure at least one site is started in Local\n   - Check that the site's database is running\n\n2. **\"MySQL socket not found\"**\n   - Verify the Local site is fully started\n   - Try stopping and restarting the site in Local\n   - Check Local's logs for MySQL startup issues\n\n3. **Connection refused**\n   - Ensure the Local site's MySQL service is running\n   - Check if another process is using the MySQL port\n   - Try restarting Local by Flywheel\n\n4. **Permission denied**\n   - Make sure the MySQL socket file has correct permissions\n   - Check if your user has access to Local's directories\n\n### Manual Configuration\n\nIf auto-detection fails, you can manually configure the connection:\n\n```bash\nexport MYSQL_SOCKET_PATH=\"/path/to/your/local/site/mysql/mysqld.sock\"\nexport MYSQL_DB=\"local\"\nexport MYSQL_USER=\"root\"\nexport MYSQL_PASS=\"root\"\n```\n\n### Debugging\n\nEnable debug logging by setting `DEBUG`:\n\n```bash\nDEBUG=mcp-local-wp mcp-local-wp\n```\n\n## Security\n\n- **Read-only operations**: Only SELECT/SHOW/DESCRIBE/EXPLAIN are allowed\n- **Single statement**: Multiple statements in one call are blocked\n- **Local development**: Designed for local environments (Local by Flywheel)\n- **No external connections**: Prioritizes Unix socket connections when available\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n### Development Guidelines\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature-name`\n3. Make your changes and add tests\n4. Ensure TypeScript compiles: `npm run build`\n5. Submit a pull request\n\n## License\n\nGPL-3.0-or-later - see the [LICENSE](LICENSE) file for details. As a WordPress-focused tool, we embrace the copyleft philosophy to ensure this remains free and open for the community.\n\n## Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/verygoodplugins/mcp-local-wp/issues)\n- **Documentation**: This README and inline code documentation\n- **Community**: Join the Model Context Protocol community discussions\n\n## Related Projects\n\n- [mcp-server-mysql](https://github.com/benborla/mcp-server-mysql) - The original MySQL MCP server that inspired this WordPress-specific version\n- [Local by Flywheel](https://localwp.com/) - The local WordPress development environment this server is designed for\n- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification\n\n---\n\nBuilt with 🧡 by [Jack Arturo](https://github.com/jackarturo) at [Very Good Plugins](https://verygoodplugins.com?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=mcp-local-wp) · Made with love for the open-source community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fmcp-local-wp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fverygoodplugins%2Fmcp-local-wp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fverygoodplugins%2Fmcp-local-wp/lists"}