bricks-mcp

▟███████████████████████████████████████████▙
█  ____  ____  ___ ____ _  ______           █
█ | __ )|  _ \|_ _/ ___| |/ / ___|   BRICKS █
█ |  _ \| |_) || | |   | ' /\___ \          █
█ | |_) |  _ < | | |___| . \ ___) |  MCP    █
█ |____/|_| \_\___\____|_|\_\____/          █
▜▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▛
  105 tools · 17 modules · MIT licensed

Printed on startup. In a real terminal the box animates in brick-by-brick (set BRICKS_BANNER=anim|static|off).

The most comprehensive open-source MCP server for Bricks Builder.

100+ tools to manage pages, templates, styles, SEO, content, and more — directly from Claude Code, Cursor, Windsurf, or any MCP-compatible AI assistant.

Architecture

Claude Code / Cursor / AI Assistant
        ↕ MCP Protocol (stdio)
   bricks-mcp (Node.js)
        ↕ REST API (Basic Auth)
   bricks-api-bridge (WordPress Plugin)
        ↕ PHP
   WordPress + Bricks Builder

The MCP server communicates with your WordPress site through the included REST API plugin. Your AI assistant gets full control over Bricks Builder — reading pages, updating elements, managing styles, and building sections.

Related MCP server: Bricks MCP

Quick Start (5 Minutes)

1. Install the WordPress Plugin

The plugin/ folder in this repo contains the Bricks API Bridge WordPress plugin. Choose one of these install methods:

Option A: ZIP Upload (easiest)

1. Download bricks-api-bridge.zip from the latest release

2. Go to WordPress Admin → Plugins → Add New → Upload Plugin

3. Upload the ZIP and click "Install Now"

4. Click "Activate"

Option B: Manual Upload via FTP/SSH

1. Clone this repo or download it

2. Copy the plugin/ folder to your WordPress installation:

   cp -r plugin/ /path/to/wordpress/wp-content/plugins/bricks-api-bridge/

3. Go to WordPress Admin → Plugins → Activate "Bricks API Bridge"

Option C: WP-CLI

# From the repo root
cd plugin && zip -r ../bricks-api-bridge.zip . && cd ..
wp plugin install bricks-api-bridge.zip --activate

After activation, the plugin registers REST API endpoints under /wp-json/bricks-bridge/v1/. No configuration needed — it works out of the box with WordPress Application Passwords.

2. Create an Application Password

In WordPress Admin → Users → Your Profile → Application Passwords:

• Enter a name (e.g., "MCP Server")

• Click "Add New Application Password"

• Copy the generated password

3. Install the MCP Server

git clone https://github.com/developer2013/bricks-mcp-open.git
cd bricks-mcp-open
npm install   # or: bun install

4. Configure Credentials

Copy .env.example to .env and fill in your details:

cp .env.example .env

WORDPRESS_URL=https://your-site.com
WORDPRESS_USER=your-username
WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx

5. Add to Your AI Assistant

Claude Code — add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "bricks": {
      "command": "node",
      "args": ["/path/to/bricks-mcp-open/index.js"]
    }
  }
}

Or with Bun (faster startup):

{
  "mcpServers": {
    "bricks": {
      "command": "bun",
      "args": ["/path/to/bricks-mcp-open/index.js"]
    }
  }
}

Claude Code iOS / Android App — open Settings → MCP Servers → Add Server:

1. Name: bricks

2. Command: node (or bun)

3. Arguments: /path/to/bricks-mcp-open/index.js

4. Environment Variables:

   • WORDPRESS_URL = https://your-site.com

   • WORDPRESS_USER = your-username

   • WORDPRESS_APP_PASSWORD = xxxx xxxx xxxx xxxx xxxx xxxx

Cursor / Windsurf — add the same config to .cursor/mcp.json in your project.

Hermes Agent (Nous Research) — add to config.yaml:

mcp_servers:
  bricks:
    command: node
    args: ["/path/to/bricks-mcp-open/index.js"]
    env:
      WORDPRESS_URL: https://your-site.com
      WORDPRESS_USER: your-username
      WORDPRESS_APP_PASSWORD: "xxxx xxxx xxxx xxxx xxxx xxxx"

Hermes has native MCP client support since v0.2.0 — all 105 tools appear in its tool list automatically. Works with any model (Hermes 3, Llama, OpenRouter, etc.).

Windows: TLS / "fetch failed" errors On Windows, Node.js ships its own bundled CA list and ignores the Windows certificate store. If your WordPress host sits behind a corporate proxy, TLS inspection, or a CA that's only trusted by Windows, every request fails with a certificate / fetch failed error. Tell Node to use the OS trust store by adding --use-system-ca before the script path in args (requires Node.js ≥ 22.15):

{
  "mcpServers": {
    "bricks": {
      "command": "node",
      "args": ["--use-system-ca", "C:\\path\\to\\bricks-mcp-open\\index.js"]
    }
  }
}

Alternatively set it via the environment instead of args: "env": { "NODE_OPTIONS": "--use-system-ca" }. On older Node versions, upgrade to ≥ 22.15 (or use NODE_EXTRA_CA_CERTS pointing to your CA bundle as a fallback).

Manage Your WordPress Site from Your Phone

Deploy the MCP server as a self-hosted MCP environment on Railway (or any Docker host), then connect it to the Claude Code mobile app. No Mac running in the background needed — the server runs 24/7 in the cloud.

How it works:

iPhone / Android (Claude Code App)
      ↕ Claude Self-Hosted MCP
Railway / Docker (MCP Server — always on)
      ↕ REST API
WordPress + Bricks Builder

Setup:

1. Deploy the MCP server to Railway using the included agent-service/Dockerfile

2. In Claude Console → MCP → Create Self-Hosted Environment

3. Generate an environment key and add it to your Railway deployment

4. The Claude Code mobile app automatically connects to your self-hosted environment

What you can do from your phone — no laptop needed:

You:  "List all my pages and their SEO scores"
You:  "Create a new landing page for my dental practice"
You:  "Update the hero headline on page 42 to 'Welcome to Our Practice'"
You:  "Run an SEO audit and fix all missing meta descriptions"
You:  "Add a testimonials section using the testimonials-slider preset"
You:  "Create a snapshot called 'before-redesign', then change the palette"

The server runs 24/7 on Railway — your phone is just the control surface. All 105 tools are available anywhere, anytime.

6. Test the Connection

Ask your AI assistant:

"Use the bricks_connection_test tool to verify my WordPress connection."

Tool Categories (100+ Tools)

Migrating from Elementor?

Switching from Elementor (Pro) to Bricks? bricks_elementor_to_bricks gives you a head start:

1. In WordPress, open the Elementor editor → ⌄ (menu) → Export Template (or Templates → Saved Templates → Export). You get a .json file.

2. Run the tool with that file:

   bricks_elementor_to_bricks  file_path="/path/to/elementor-export.json"

3. You get a ready-to-review Bricks element array plus a coverage report.

4. Review it, then push with bricks_update_page (take a snapshot first) or bricks_import_page.

How it works: a purely structural translation — no headless browser, no rendering, no write to your site. Common widgets (heading, text, button, image, icon, divider, spacer) and the section/column/container structure map straight to native, editable Bricks elements. Widgets without a native equivalent (e.g. Pro sliders, forms, loops) become clearly-labelled placeholder blocks carrying a preview of their original content — so nothing is lost silently and you always see where and what to rebuild by hand. line-height is converted to a correct unitless ratio so you never inherit Elementor's px values as Bricks multipliers.

Keeping your CSS editable in Bricks

The whole point of Bricks is a visual builder — so CSS the assistant writes should stay editable in Bricks, not vanish into a place you can't reach. This plugin can inject per-page CSS into a private bundle (_bab_page_assets, output at wp_head priority 9997 — before element CSS) via bricks_update_page_assets. That bundle is not shown anywhere in the Bricks builder and silently overrides what the builder displays — great for infrastructure CSS (@font-face, :root{--vars}, @keyframes, critical above-the-fold), but the wrong home for the layout/responsive/visual CSS you'll want to tweak by hand later. (This is exactly the r/BricksBuilder feedback: "plugin-managed page CSS that a human can't edit defeats the purpose of using Bricks.")

Where editable CSS belongs (priority order):

1. Native element settings — padding, typography, colors, etc. (fully visual controls)

2. Element _cssCustom — per-element custom CSS, editable on the element's CSS tab

3. Page customCss — bricks_update_page_settings → Bricks Page Settings → Custom CSS

4. Global classes — editable in the Class Manager (build them with native settings, not _cssCustom, which is not compiled into page CSS via the API path)

The editability guard

To stop editable CSS from leaking into the invisible bundle, the guard classifies the css field of bricks_update_page_assets and acts in three modes:

Enable it by adding one line to your wp-config.php (above /* That's all, stop editing! */):

// Bricks API Bridge — warn (or 'block') when editable CSS is sent to the private page-assets bundle
define( 'BAB_GUARD_EDITABLE_CSS', 'warn' );

(Or, without editing files: wp option update bab_guard_editable_css warn.) On the MCP side, the bricks_update_page_assets tool warns by default; set the env var BRICKS_MCP_BLOCK_EDITABLE_CSS=1 to hard-block there too. Infrastructure CSS always passes — use the css_critical / css_deferred fields for it.

Multi-Site Support

Manage multiple WordPress sites from a single MCP server. Copy sites.json.example to sites.json:

{
  "default": "production",
  "sites": {
    "production": {
      "label": "Live Site",
      "url": "https://your-site.com",
      "username": "admin",
      "password": "xxxx xxxx xxxx xxxx xxxx xxxx"
    },
    "staging": {
      "label": "Staging",
      "url": "https://staging.your-site.com",
      "username": "admin",
      "password": "xxxx xxxx xxxx xxxx xxxx xxxx"
    }
  }
}

Switch sites at runtime:

"Switch to the staging site."

Custom sites.json location. If you collect your MCP servers in one folder and keep site configs elsewhere, set BRICKS_SITES_PATH to point at the file — absolute, relative (to the working directory), or ~-prefixed all work:

BRICKS_SITES_PATH=~/mcp-config/bricks-sites.json

When set, a missing file fails loudly at startup (instead of silently falling back to the WORDPRESS_* env vars), so a typo in the path can't connect you to the wrong site. No need to symlink sites.json into the server folder.

Usage Examples

Build a page section

"Create a hero section on page 42 with a full-width background, centered heading 'Welcome', a subtitle, and a CTA button."

Manage styles

"Update the color palette — set the primary color to #2563EB and secondary to #7C3AED."

SEO optimization

"Run an SEO audit on all published pages and auto-fix missing meta descriptions."

Backup before changes

"Create a snapshot of page 42 named 'before-redesign', then update the hero section."

Plugin Features

The included WordPress plugin (bricks-api-bridge) provides:

• REST API endpoints for all Bricks Builder data

• Security hardening — rate limiting, user enumeration protection, security headers

• Responsive inference — automatic mobile/tablet breakpoint generation

• Element validation — catches invalid IDs, broken parent-child links

• Auto-fix — corrects common CSS issues (overflow, grid, container width)

• Backup system — multi-slot backups + named snapshots

• Design token import/export — JSON, ACSS, Tailwind formats

Feature Comparison

Requirements

• Node.js >= 18 or Bun >= 1.0 (Windows behind a proxy/custom CA: use Node ≥ 22.15 with --use-system-ca — see Windows TLS note)

• WordPress >= 6.0

• Bricks Builder >= 2.0

• PHP >= 8.0

Agent Service (Autonomous Page Builder)

The agent-service/ directory contains an autonomous agent that builds entire WordPress pages from industry briefs — using Claude + the MCP server in a 5-phase pipeline:

Industry Brief → Historian → Design → Code → Update → QA → Fix Loop

• Build from your iPhone or Android — Use the Telegram bot or the Claude Code mobile app as your control center: trigger builds, QA, fixes, and screenshots from anywhere

• CLI Mode — Single builds or overnight batch processing

• Budget Control — Per-phase cost caps, total cost tracking

• Docker Ready — Deploys to Railway, Fly.io, or any container host

See agent-service/README.md for setup instructions.

Premium

Looking for more? The premium edition includes 260+ tools with:

• AI Build Pipeline — Build entire pages from a URL in one command

• Learning System — Remembers CSS fixes and improves over time

• Math Library — 33 modules for design tokens, color harmony, spring physics

• Visual QA — Puppeteer screenshots, pixel comparison, accessibility audits

• Design Intelligence — Brand archetypes, competitive benchmarking, typography suggestions

• WooCommerce, ACF, Gravity Forms integrations

• Bio-inspired animations — Levy stagger, density-intensity, quorum sensing

Reach out for premium access

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE.