How to connect

Connecting your AI client to Blockish is the most critical step. Once connected, your AI (like Cursor, Claude Desktop, or Windsurf) gains the ability to read your WordPress database, validate schemas, and build layouts directly in the Gutenberg editor.

Blockish uses the Model Context Protocol (MCP) to make this secure. We’ve built a Configuration Wizard that automates 99% of the setup process.

1. The Configuration Wizard (Recommended)

The wizard generates a single terminal command that automatically writes the MCP configuration file for your specific AI client.

Step-by-step Setup

1. Open the Wizard: In WordPress admin, go to Blockish → MCP Server and click Start Configuration Wizard.
2. Select OS & Node.js: Choose Mac, Windows, or Linux. If you don’t have Node.js (or aren’t sure), select No — the command installs it for you.
3. Choose Your AI Client: Cursor, Claude Desktop, Windsurf, or another supported app.
4. Generate Password: Click Auto-Generate Password for a secure Application Password (not your real admin password).
5. Run the Command: Click Generate Command, copy it, paste into Terminal, and press Enter.

2. The Most Important Step: Restart Your AI

Your AI client will not see the new tools until it is fully restarted. Closing the window is not enough — quit the background process too.

• Mac: App menu → Quit, or Cmd + Q.
• Windows: Close the window and check the System Tray so it isn’t still running.

Once fully quit, reopen the application.

3. Verifying the Connection

Open a new chat in your AI client:

Cursor / Windsurf: Check the MCP (puzzle piece) icon or Tools menu and confirm the blockish server is active.

Claude Desktop: Click the plug icon in the chat bar to see active tools.

Test prompt: List all available tools from the Blockish MCP server. You should see tools like blockish-write-blog and blockish-manage-post.

4. Troubleshooting & Manual Setup

If the terminal command fails (often file permissions), add the configuration manually.

Manual JSON Configuration

Edit your AI client’s config file:

• Cursor (Mac/Linux): ~/.cursor/mcp.json
• Cursor (Windows): %USERPROFILE%\.cursor\mcp.json
• Claude Desktop (Mac): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Windsurf (Mac/Linux): ~/.codeium/windsurf/mcp_config.json

Add this inside the mcpServers object. Replace the placeholders with your site URL, WordPress username, and Application Password from the wizard:

{
  "mcpServers": {
    "blockish": {
      "command": "npx",
      "args": [
        "-y",
        "@blockish/mcp-server",
        "--url",
        "https://YOUR-SITE.com",
        "--username",
        "YOUR_WP_USERNAME",
        "--password",
        "YOUR_APPLICATION_PASSWORD"
      ]
    }
  }
}

Common Issues

‘Tool not found’ or the AI writes raw HTML

Ask it to use Blockish MCP tools and follow each tool’s instructions — no shortcuts.

‘npx: command not found’

Install Node.js from nodejs.org, restart your computer, then run the wizard command again.