Read-only MCP server for exploring WordPress MySQL/MariaDB databases. Provides schema inspection, relationship mapping, and safe SQL querying.

• Auto-detects WordPress table prefix
• Full schema generation (JSON / CSV)
• WordPress relationship mapping (posts, terms, meta, users, comments)
• Raw SQL querying with safety guardrails (SELECT only)
• Multisite support
• Query timeout and row limits
• Post search by title/content
• Extensible to plugin tables (WooCommerce, ACF, etc.)

• Read-only: Only SELECT, SHOW, DESCRIBE, EXPLAIN allowed
• SQL injection protection: Parameterized queries throughout
• Comment stripping: SQL comments removed before validation
• Multi-statement blocking: Semicolon injection prevented
• System schema blocking: No access to information_schema, mysql, performance_schema, sys
• Keyword blocking: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, etc.
• Timeout enforcement: MySQL MAX_EXECUTION_TIME + Python asyncio
• Row limits: Configurable per-query limits (max 1000)

• Python 3.10+
• MySQL or MariaDB database
• A read-only database user (recommended)

No installation required when using uvx. The MCP server is installed automatically when configured.

Alternatively, install manually:

pip install wp-db-mcp

Create a dedicated read-only MySQL user:

CREATE USER 'wp_mcp_reader'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT SELECT ON your_wordpress_db.* TO 'wp_mcp_reader'@'localhost';
FLUSH PRIVILEGES;

Add to your MCP settings JSON:

{
  "mcpServers": {
    "wp-db": {
      "command": "uvx",
      "args": [
        "--from",
        "wp-db-mcp",
        "wp-db-mcp"
      ],
      "env": {
        "WP_DB_HOST": "127.0.0.1",
        "WP_DB_PORT": "3306",
        "WP_DB_USER": "wp_mcp_reader",
        "WP_DB_PASSWORD": "your_password",
        "WP_DB_NAME": "your_wordpress_db"
      }
    }
  }
}

claude mcp add wp-db \
  -e WP_DB_HOST=127.0.0.1 \
  -e WP_DB_USER=wp_mcp_reader \
  -e WP_DB_PASSWORD=secret \
  -e WP_DB_NAME=mysite \
  -- uvx --from wp-db-mcp wp-db-mcp

Local uses Unix sockets. Find your socket path in Local's site info (Database tab), then:

{
  "mcpServers": {
    "wp-db": {
      "command": "uvx",
      "args": [
        "--from",
        "wp-db-mcp",
        "wp-db-mcp"
      ],
      "env": {
        "WP_DB_SOCKET": "/Users/you/Library/Application Support/Local/run/XXXXXXXX/mysql/mysqld.sock",
        "WP_DB_USER": "root",
        "WP_DB_PASSWORD": "root",
        "WP_DB_NAME": "local"
      }
    }
  }
}

To find your socket path in Local:

1. Open Local app
2. Select your site
3. Click "Database" tab
4. Look for "Socket" path

List all tables with engine, row count, and size. Supports multisite site_id filter.

Show columns, types, keys, and indexes for a specific table. Accepts full name or core suffix (e.g. posts instead of wp_posts).

Generate a complete database schema with all columns, indexes, and detected relationships. Outputs JSON or CSV. Toggle include_plugins to include non-core tables. Uses optimized batch queries.

Map how WordPress tables relate to each other:

• wp_posts -> wp_postmeta (via post_id)
• wp_posts -> wp_term_relationships -> wp_term_taxonomy -> wp_terms
• wp_posts -> wp_comments (via comment_post_ID)
• wp_users -> wp_usermeta (via user_id)
• wp_users -> wp_posts (via post_author)
• wp_terms -> wp_termmeta (via term_id)
• Self-referential: post_parent, comment_parent, taxonomy parent

Execute raw SELECT queries with safety checks. Blocked: INSERT, UPDATE, DELETE, DROP, system schemas, and all other write/DDL operations. Row limit and timeout enforced. Returns has_more indicator for pagination.

Search posts by title or content using LIKE matching. Filter by post_type and post_status. Returns content preview (first 200 chars).

Get all terms for a post, traversing the full relationship chain. Filter by taxonomy.

Get all posts for a term. Filter by post_type and post_status. Returns has_more indicator.

List all taxonomies registered in the database with term counts and total usage.

Get all meta key-value pairs for a post. Filter by meta_key (exact or LIKE pattern).

Get all meta key-value pairs for a user. Filter by meta_key. Note: In multisite, user meta is shared across all sites.

Get all meta key-value pairs for a comment. Filter by meta_key.

These tools query relationships created by the WP Content Connect library.

Discover all relationship names registered in WP Content Connect. Queries both post_to_post and post_to_user tables to list distinct relationship names with their connection counts. Useful for exploring what relationships exist before querying specific connections.

Get posts connected to a post via the post_to_post table. Supports filtering by relationship name and direction (from, to, or any).

Get users connected to a post via the post_to_user table. Supports filtering by relationship name.

Get posts connected to a user via the post_to_user table (reverse lookup). Supports filtering by relationship name.

List all post connections for a given relationship name. Returns all connection pairs with both posts' details (ID, title, type) and the relationship order.

These tools support the "shadow taxonomy" pattern where posts are related through taxonomy terms that store the source post ID in term meta.

Discover shadow taxonomies in the database. Identifies taxonomies where terms have meta values that reference valid post IDs. Returns taxonomy name, meta key used, term count, and linked post count. Useful for exploring what shadow relationships exist.

Find posts related via a shadow taxonomy. Given a source post, finds all terms where the term meta matches the post ID, then returns all posts assigned to those terms.

Parameters:

• post_id: Source post ID
• taxonomy: Shadow taxonomy name (e.g., speaker_shadow)
• meta_key: Term meta key storing the post ID (e.g., shadow_post_id)

Get the source post for a shadow term (reverse lookup). Given a term ID, finds the post whose ID is stored in the term's meta.

List all posts using a shadow taxonomy relationship. Returns all posts assigned to shadow terms, with term info (ID, name) and source post details (ID, title, type).

Once configured, just ask questions in natural language. The AI will automatically use the appropriate tools.

• "What tables are in my WordPress database?"
• "Show me the structure of the posts table"
• "What are all the relationships between WordPress tables?"
• "Generate the full database schema"

• "How many published posts do I have?"
• "Search for posts containing 'hello'"
• "What taxonomies are registered?"
• "List all categories and their post counts"

• "Get all terms for post ID 1"
• "Show me the meta data for user ID 1"
• "What posts are in the 'uncategorized' category?"
• "Get all comments for post ID 5"

• "Run this query: SELECT post_title, post_date FROM wp_posts WHERE post_status = 'publish' ORDER BY post_date DESC LIMIT 10"
• "Show me the 5 most recent users"
• "Count posts by post type"

For sites using the WP Content Connect library:

• "What Content Connect relationships are defined in the database?"
• "List all connection types/relationship names"
• "What posts are connected to post ID 42?"
• "Find all posts connected to post 15 via the 'related_articles' relationship"
• "Show posts connected FROM post 100 (where it's the source)"
• "Show posts connected TO post 100 (where it's the target)"
• "What users are connected to post ID 50?"
• "Find all speakers connected to this event post"
• "What posts is user ID 5 connected to?"
• "Show all events that user 12 is associated with"
• "List all posts using the 'related_articles' relationship"
• "Show me all connections for the 'speakers' relationship"

For sites using shadow taxonomies (where posts are related through taxonomy terms that store post IDs in term meta):

• "What shadow taxonomies exist in the database?"
• "Discover all shadow taxonomy relationships"
• "Find all sessions related to speaker post ID 25 using the 'speaker_shadow' taxonomy"
• "What posts are related to post 100 via shadow taxonomy 'event_shadow' with meta key 'shadow_post_id'?"
• "Get the source post for shadow term ID 150"
• "Which speaker post does term ID 42 represent?"
• "List all posts using the 'speaker_shadow' taxonomy with meta key 'shadow_post_id'"
• "Show me all relationships in the 'event_shadow' shadow taxonomy"

For multisite installations, pass site_id to any tool:

• site_id=None or site_id=1 -> main site (uses base prefix, e.g. wp_)
• site_id=2 -> sub-site 2 (uses wp_2_)
• site_id=3 -> sub-site 3 (uses wp_3_)

The wp_get_relationships tool auto-detects all multisite prefixes.

Note: wp_users and wp_usermeta are shared across all sites in multisite.

Set include_plugins=true in wp_get_schema to include all tables beyond WordPress core.

For WooCommerce, the schema will include tables like:

• wp_wc_orders, wp_wc_order_product_lookup
• wp_woocommerce_* tables

Use wp_query to explore any table directly.

MIT