brilliant-directories-mcp MCP工具

Official Brilliant Directories MCP Server — Setup Guide

Universal AI integration for your BD site. Give any AI agent full access to your Brilliant Directories site with one API key.

Manage members, posts (single-image and multi-image), leads, reviews, top and sub categories, email templates, pages (homepage, landing pages), 301 redirects, smart lists, widgets, menus, forms, tags, membership plans, and more — across every resource BD exposes via its REST API.

This guide walks you through connecting your AI of choice (Claude, Cursor, etc.) to your BD site. Pick your AI app below, paste two things, restart. Most setups take under 5 minutes.

Setup by Platform

<a id="the-config-block"></a>

Each platform has two options:

• 🚀 Easy config block — points at our hosted MCP at https://brilliantmcp.com. No Node.js, no install, no terminal. Starts working the moment you save and restart your AI app.
• 🛠️ Advanced config block — spawns the MCP as a npx child process on your machine. Use when you want the MCP on your own hardware.

Needs Node.js installed first — get it from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> (click Get Node.js® to download, then click Windows Installer (.msi) — Mac: macOS Installer — and DOUBLE-CLICK the downloaded file to install it).

Both give the full BD tool surface, same instructions, same lean shapers, same safety guards.

🚀 Easy config block (recommended — 30-second install)

In your AI client's MCP config (Cursor, Windsurf, Cline, Codex, n8n, etc.), add this entry:

{
  "mcpServers": {
    "brilliant-directories": {
      "url": "https://brilliantmcp.com",
      "headers": {
        "X-Api-Key": "ENTER_API_KEY",
        "X-BD-Site-URL": "https://www.your-site.com"
      }
    }
  }
}

Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL (full canonical form — https://, exact host, no trailing slash, see Requirements).

⚠️ Claude Desktop doesn't accept the Easy block — use the Advanced block in the Claude Desktop section.

Save, then fully quit and reopen the AI app. Saving alone is not enough — every AI client loads MCP servers only at fresh launch, not on hot-reload. Done. Working? Skip to "What you can ask the AI".

Need a client-specific walkthrough? Jump to your platform's section below.

Install

1. Open claude.ai → Settings → Customize → Skills → Upload Skill.
2. Upload the bd-skill-content.zip file you downloaded.
3. Ensure your BD MCP is connected (either the hosted https://brilliantmcp.com or the npm-installed local server).
4. Start a chat and tell Claude what you want: "create event posts for upcoming fitness events in Austin."

Build from source

The skill source lives in bd-skill-content/. Rebuild the zip yourself:

```bash node scripts/build-skill-zip.js

🚨 API PERMISSIONS — DO NOT SKIP THIS

New BD API keys ship locked down — only member read/write is enabled by default.

Every other resource (web pages, forms, menus, tags, email templates, reviews, leads, categories, post types, widgets, etc.) lives behind an "Advanced Endpoints" toggle and returns 403 API Key does not have permission to access this endpoint until you flip it on.

This catches almost every first-time user. If your AI can list members but can't create a page or update a form, stop debugging — it's this.

Turn on Advanced Endpoints:

1. BD Admin → Developer Hub
2. Find your API key in the list → Actions dropdown → Permissions
3. Click the Advanced Endpoints tab
4. Toggle everything ON (or cherry-pick only the resources you'll use — but ALL ON is the fastest way to stop tripping over this)
5. Click Save Permissions

The change is immediate — no key rotation, no AI restart needed. Re-run the failed request and it'll succeed.

Want to stop the AI from deleting anything? Uncheck every delete action under Advanced Endpoints. The AI will still be able to read, create, and update — but any delete* tool call will return 403 instead of wiping data. Good baseline for production sites where the AI shouldn't be trusted with destructive operations.

Why BD locks it down by default: least-privilege. A leaked key with baseline-only permissions can only read/write members on your site, not rewrite your whole directory. Once you've decided which endpoints your agent actually needs, you can pare the permissions back down to just those.

Zapier

The "MCP Client by Zapier" app only supports OAuth / Bearer Token — no custom-headers field, so it cannot authenticate against our Worker (same single-token limitation as Make).

Use one of these paths instead: - BD's existing Zapier app (if it covers what you need) — same underlying API, same API key. - Webhooks by Zapier against https://www.your-site.com/api/v2/*, with Custom Headers X-Api-Key: <your key> and X-BD-Site-URL: https://www.your-site.com. This hits BD's REST API directly and skips MCP entirely — every BD operation reachable.

---

Verify your API key

curl -H "X-Api-Key: ENTER_API_KEY" https://www.your-site.com/api/v2/token/verify

Universal MCP Client Reference

Any generic MCP client (LibreChat, custom agents, etc.) asks the same four questions. Use this table to fill any of them in.

n8n is the exception. n8n's Streamable HTTP client has upstream bugs, so n8n users must use Transport = Server Sent Events (Deprecated) + URL https://brilliantmcp.com/sse (with the /sse path). See the n8n section for the exact field values. Our server supports both transports — n8n just happens to need the legacy one today.

How to tell if any other MCP client will work: the blocker is always "can this client send custom HTTP headers?" If the UI shows a Custom Headers / Multiple Headers / HTTP Headers field, you're good — plug in our two headers. If the UI only offers OAuth or Bearer Token, that client cannot reach our Worker today.

Claude extension inside Cursor

If you chat with Claude inside Cursor (the Anthropic "Claude" extension installed from the Cursor extension marketplace), that extension has its OWN MCP config — separate from Cursor's native agent. Installing in one doesn't install in the other.

Note: the Claude extension and the Claude Code CLI both read the SAME file — ~/.claude.json (Windows: C:\Users\<you>\.claude.json). If you've already set up Claude Code per the section above, the BD MCP is already loaded for the Claude extension too. This section covers customers who only use the Claude extension and don't have the CLI installed.

Two different MCP configs. Two different places the tools show up.

1. Claude extension (inside Cursor or Claude Code CLI) - Config file (Windows): C:\Users\<you>\.claude.json - Config file (Mac / Linux): ~/.claude.json - Tools appear: when you chat with Claude — ask "what tools do you have" or type /mcp

2. Cursor's native agent - Config file (Windows): C:\Users\<you>\.cursor\mcp.json - Config file (Mac / Linux): ~/.cursor/mcp.json - Tools appear: Cursor Settings → Tools & MCP

Easiest setup — edit the JSON file in Notepad (NO terminal, NO claude CLI needed):

⚠️ STEP 1 — Install Node.js FIRST (before editing the config below): - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click Get Node.js® - Download: Windows Installer (.msi) or macOS Installer - Double-click the file → click Next through every prompt to fully install Node.js Skip this and you'll see "no MCP servers" with spawn npx ENOENT in the log.

1. Open the file. Paste the path into File Explorer's address bar (Windows) or Finder's Go → Go to Folder (Mac). If it doesn't exist yet, create a new empty text file at that path named exactly .claude.json.
2. Paste this inside. If the file already has content with an mcpServers key, merge the "brilliant-directories": {...} entry into the existing mcpServers object — don't overwrite other entries.

   {
     "mcpServers": {
       "brilliant-directories": {
         "command": "npx",
         "args": [
           "-y",
           "--prefer-online",
           "brilliant-directories-mcp@latest",
           "--api-key", "ENTER_API_KEY",
           "--url", "https://www.your-site.com"
         ]
       }
     }
   }
   

1. Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL (include https://, no trailing slash).
2. Save the file, then fully quit and reopen Cursor so the Claude extension picks up the new config. Saving alone is not enough.
3. Chat with Claude and ask "what tools do you have?" — you should see brilliant-directories tools listed.

Cursor's Tools & MCP panel will stay empty — that's expected. Claude's extension reads ~/.claude.json; Cursor's panel only reflects ~/.cursor/mcp.json. If you want BD tools in BOTH surfaces, also do the Cursor section install.

Alternative — if you have the claude CLI installed (most users don't — skip if you don't know what it is): run this in any terminal:

claude mcp add brilliant-directories -- npx -y --prefer-online brilliant-directories-mcp@latest --api-key ENTER_API_KEY --url https://www.your-site.com

The CLI writes the same JSON to ~/.claude.json for you — same end result as editing by hand.

---

Cline (VS Code extension)

1. Open VS Code with the Cline extension installed.
2. Click the Cline icon in the VS Code sidebar to open the Cline panel.
3. In Cline's top nav, click the MCP Servers icon.
4. Click Configure MCP Servers — opens the Cline MCP config file in VS Code.
5. Paste one of these (Easy is recommended):

🚀 Easy (recommended — no Node.js install required):

{
  "mcpServers": {
    "brilliant-directories": {
      "url": "https://brilliantmcp.com",
      "headers": {
        "X-Api-Key": "ENTER_API_KEY",
        "X-BD-Site-URL": "https://www.your-site.com"
      }
    }
  }
}

🛠️ Advanced (runs on your machine, needs Node.js):

⚠️ STEP 1 — Install Node.js FIRST (before pasting the config below): - Go to <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a> → click Get Node.js® - Download: Windows Installer (.msi) or macOS Installer - Double-click the file → click Next through every prompt to fully install Node.js Skip this and you'll see "no MCP servers" with spawn npx ENOENT in the log.

{
  "mcpServers": {
    "brilliant-directories": {
      "command": "npx",
      "args": [
        "-y",
        "--prefer-online",
        "brilliant-directories-mcp@latest",
        "--api-key", "ENTER_API_KEY",
        "--url", "https://www.your-site.com"
      ]
    }
  }
}

Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL. Save, then fully quit and reopen VS Code. Saving alone is not enough — Cline loads MCP servers only at fresh launch, not on panel reload or toggle.

1. Back in the MCP Servers panel, confirm brilliant-directories appears — toggle it on if not already.

"Fully quit" means more than closing the window — Cline loads MCP servers only at a true VS Code relaunch: > - Windows: right-click the VS Code icon in the system tray (bottom-right, may be hidden under ^) → Quit, then reopen > - Mac: Cmd+Q or menu bar → Code → Quit Visual Studio Code, then reopen

---

Alternative A — Cursor Settings GUI (manual, no terminal)

1. Open Cursor. 2. Open settings: - Mac: menu bar → Cursor → Settings → Cursor Settings - Windows / Linux: File → Preferences → Cursor Settings - Or: Command Palette (Cmd/Ctrl+Shift+P) → type Open MCP Settings 3. In the sidebar, click Tools & MCP. 4. Click New MCP Server. 5. Paste the config block. Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL. 6. Click Save, then fully quit and reopen Cursor. Saving alone is not enough — Cursor loads MCP servers only at fresh launch.

Alternative B — Edit the config file directly

Use this if the GUI doesn't show "Tools & MCP" or the "New MCP Server" button silently fails. Same result as the GUI method.

Cursor reads from mcp.json in a hidden .cursor folder in your home directory.

Mac / Linux

1. Open Finder (Mac) or your file manager (Linux). 2. Cmd+Shift+G (Mac) or Ctrl+L (Linux) to open a "Go to Folder" input. 3. Type ~/.cursor → Enter. - If "Folder doesn't exist": navigate to ~/ and create a new folder named exactly .cursor (leading dot). Retry. 4. Inside .cursor, open mcp.json in TextEdit / any text editor. If missing: create it. TextEdit users: File → New → Format menu → Make Plain Text first, then save as mcp.json (not mcp.json.txt). 5. Paste the config block. Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL. Save, then fully quit and reopen Cursor.

Windows

1. Windows key → type File Explorer → Enter. 2. Click the address bar at the top. Type %USERPROFILE%\.cursor → Enter. - If "Windows can't find": go to %USERPROFILE%, right-click → New → Folder → name it exactly .cursor (leading dot). Retry. 3. Inside .cursor, open mcp.json in Notepad. If missing: right-click empty area → New → Text Document → rename to mcp.json (click Yes to the extension warning). - Can't see .txt / .json extensions? File Explorer → View menu → check File name extensions. 4. Paste the config block. Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL. Save, then fully quit and reopen Cursor.

</details>

---

Troubleshooting

Verify your setup with one command. Paste in a terminal (Mac: Terminal.app · Windows: PowerShell). Replace ENTER_API_KEY with your BD API key and https://www.your-site.com with your BD site URL:

npx --prefer-online brilliant-directories-mcp@latest --verify --api-key ENTER_API_KEY --url https://www.your-site.com

Debug mode — see exactly what's happening:

npx --prefer-online brilliant-directories-mcp@latest --debug --verify --api-key ENTER_API_KEY --url https://www.your-site.com

Drop --verify to start the full MCP stdio server with debug logging — it will appear to hang in a regular terminal because MCP servers run forever over stdio, waiting for an AI client to connect. Use --debug --verify for one-shot debugging from a shell.

Common issues: - AI says "no tools" or "I don't have access" — you didn't fully quit and reopen your AI app after setup. Fully quit (Mac Cmd+Q; Windows right-click taskbar → Quit), then reopen. - 401 Unauthorized — API key is wrong, revoked, or lacks permission for the endpoint. Regenerate in BD Admin → Developer Hub. - 403 API Key does not have permission to access this endpoint — this specific endpoint isn't granted on your key. Edit the key in BD Admin → Developer Hub and enable the missing endpoint (the error names it). - 404 Not Found — your site URL is wrong. Must include https:// and NO trailing slash, and match the canonical form your site responds at (include www. if your site uses it). Correct: https://www.mysite.com. Wrong: mysite.com, https://mysite.com/, or https://mysite.com when the site actually serves at www.mysite.com. - 429 Too Many Requests — rate limit hit (100 req/60s default). Wait 60 seconds, or email BD support to raise your site's limit up to 1,000/min. - Unknown tool (from Claude) — the MCP server didn't load. Fully quit + reopen the AI app first. If still broken, the npx cache has a stale install: - Windows PowerShell: Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" - Mac/Linux Terminal: rm -rf ~/.npm/_npx - Then fully quit + reopen. The -y in your config makes npx re-download automatically — you do NOT need npm install -g brilliant-directories-mcp. - npx: command not found or spawn npx ENOENT — Node.js isn't installed (or your AI app started before Node was installed). Install from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a>, then fully quit and reopen your AI app. Still seeing it? Reboot your computer (rare, but fixes a Windows PATH-cache issue that occasionally lingers after install). - ETARGET No matching version found — your local npm cache is stale. Adding --prefer-online to your config args (per the snippets above) prevents this; if your config doesn't have it yet, run npm cache clean --force and restart your AI app. - "not valid MCP server configurations" (Claude Desktop) — claude_desktop_config.json doesn't accept url-shaped blocks. Use the Advanced (npm/stdio) config from the Claude Desktop section. Windows users on the Microsoft Store version of Claude Desktop should also uninstall and reinstall from <a href="https://claude.ai/download" target="_blank" rel="noopener noreferrer">claude.ai/download</a> (the Store version sandboxes the config in ways that can break MCP loading silently).

---

FAQ

Does this cost anything? The MCP server is free (MIT license, open source). Your AI agent's subscription (Claude, Cursor, etc.) is separate. API calls to your BD site count against your site's rate limit but don't cost extra.

Is my data sent to Anthropic / OpenAI / third parties? Your BD site data passes from your BD site directly to the AI client on your machine, then to the AI provider you use (Anthropic, OpenAI, etc.) as part of your conversation with the AI. The MCP server itself doesn't relay data anywhere else — no telemetry, no third-party servers in between.

Can I connect more than one BD site? Yes. Add multiple entries under mcpServers with different names (e.g. bd-site-a, bd-site-b), each with its own API key and URL. Your AI will see tools from both.

Can my team share one key, or should everyone have their own? Each person should generate their own API key (BD Admin → Developer Hub). Keys are per-user so revoking one doesn't break anyone else.

How do I disconnect / remove the MCP? - Claude Code: claude mcp remove brilliant-directories - Cursor / Windsurf / Cline: delete the brilliant-directories entry from the MCP config JSON file, save, fully quit and reopen the app.

How do I undo something the AI did? BD's API doesn't have a universal undo. For members, prefer updateUser active=3 (Canceled) over deleteUser — it's reversible. For destructive operations, back up first or test on one record.

Can I try this safely on a test site before production? Yes. Generate a separate API key on a BD staging/dev site, set that URL + key in your MCP config. Once you trust the workflow, switch to production.

How do I know which endpoints my API key has permission for? Check your key in BD Admin → Developer Hub. When you hit 403 API Key does not have permission to access this endpoint, the error names the denied endpoint — enable it on the key, save, retry.