Brilliant Directories API — Universelle KI-Integration

npm version license MCP

Geben Sie jedem KI-Agenten mit einem API-Schlüssel vollen Zugriff auf Ihre BD-Website.

170 Endpunkte über 32 Ressourcen: Mitglieder, Leads, Beiträge, Bewertungen, Kategorien, E-Mail-Vorlagen, Seiten (Startseite, Landingpages), 301-Weiterleitungen, Smart Lists, Widgets, Menüs, Formulare, Mitgliedschaftspläne und mehr.

30-Sekunden-Schnellstart

Ein Befehl. Zwei Fragen beantworten. Fertig.

npx brilliant-directories-mcp --setup

Der Assistent fragt nach Ihrer BD-Website-URL und Ihrem API-Schlüssel, testet die Verbindung, fragt, welche App Sie verwenden (Cursor / Claude Desktop / Windsurf / Claude Code) und schreibt die Konfiguration für Sie. Kein JSON-Editieren erforderlich.

Starten Sie Ihre App neu und fragen Sie dann Ihre KI:

"List members on my BD site"

Sie erhalten Ihren API-Schlüssel unter BD Admin > Developer Hub > Generate API Key.

Für KI-Agenten / Skripte (nicht-interaktiv)

Wenn Sie von einem KI-Agenten geleitet werden, können Sie einen einzelnen Befehl mit allen vorausgefüllten Daten einfügen:

npx brilliant-directories-mcp --setup --url https://your-site.com --api-key YOUR_KEY --client cursor

Dies führt das vollständige Setup ohne weitere Eingabeaufforderungen durch. Ersetzen Sie cursor durch claude-desktop, windsurf, claude-code oder print (gibt die JSON-Konfiguration aus, anstatt eine Datei zu schreiben).

Setup nach Plattform

Claude Code / Cursor / Windsurf / Cline (MCP)

Option A — npx (empfohlen, keine Installation erforderlich):

claude mcp add bd-api -- npx brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com

Option B — Globale Installation:

npm install -g brilliant-directories-mcp
claude mcp add bd-api -- brilliant-directories-mcp --api-key YOUR_KEY --url https://your-site.com

Cursor / Windsurf / Cline — fügen Sie dies Ihrer MCP-Konfigurationsdatei hinzu (~/.cursor/mcp.json usw.):

{
  "mcpServers": {
    "bd-api": {
      "command": "npx",
      "args": ["-y", "brilliant-directories-mcp", "--api-key", "YOUR_KEY", "--url", "https://your-site.com"]
    }
  }
}

Fragen Sie dann Ihre KI: "List all members on my BD site" oder "Create a new member with email john@example.com"

ChatGPT (GPT Actions)

In Ihrem GPT: Configure > Actions > Create new action

Wählen Sie unter Schema die Option Import from URL und fügen Sie Folgendes ein:

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

Wenn Sie nach bd_site_url gefragt werden, geben Sie Ihre BD-Website ein (z. B. https://mysite.com)
Legen Sie die Authentifizierung fest: API Key, Auth Type: Custom, Header Name: X-Api-Key, fügen Sie Ihren Schlüssel ein

n8n

Option A — OpenAPI-Spezifikation importieren (empfohlen):

Importieren Sie die Spec-URL als benutzerdefinierte API-Definition:

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

n8n fragt beim Import nach Ihrer BD-Website-URL und Ihrem API-Schlüssel. Kein Bearbeiten von Dateien erforderlich.

Option B — Einfacher HTTP-Request-Node:

Erstellen Sie einen neuen Workflow, fügen Sie einen HTTP Request-Node hinzu
Einstellungen:
- Methode: GET
- URL: https://your-site.com/api/v2/user/get
- Header: X-Api-Key: YOUR_KEY

Make / Zapier

Make: Erstellen Sie eine benutzerdefinierte App unter Verwendung der OpenAPI-Spezifikation oder verwenden Sie das HTTP-Modul mit dem X-Api-Key-Header.

Zapier: Wenn Sie bereits die BD Zapier-App verwenden, nutzt diese dieselbe zugrunde liegende API. Verwenden Sie für neue Endpunkte Webhooks by Zapier mit dem X-Api-Key-Header.

curl / Beliebiger HTTP-Client

# Verify your API key
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/token/verify

# List members
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/get?limit=10

# Create a member
curl -X POST -H "X-Api-Key: YOUR_KEY" \
  -d "email=new@example.com&password=secret123&subscription_id=1&first_name=Jane&last_name=Doe" \
  https://your-site.com/api/v2/user/create

# Search members
curl -X POST -H "X-Api-Key: YOUR_KEY" \
  -d "q=dentist&address=Los Angeles&limit=10" \
  https://your-site.com/api/v2/user/search

# Update a member
curl -X PUT -H "X-Api-Key: YOUR_KEY" \
  -d "user_id=42&company=New Company Name" \
  https://your-site.com/api/v2/user/update

Fehlerbehebung

Überprüfen Sie Ihr Setup mit einem Befehl:

npx brilliant-directories-mcp --verify --api-key YOUR_KEY --url https://your-site.com

Gibt OK aus, wenn die Anmeldedaten funktionieren, andernfalls FAIL mit der Fehlermeldung. Ein guter erster Schritt bei Verbindungsproblemen.

Debug-Modus — sehen Sie genau, was passiert:

npx brilliant-directories-mcp --debug --verify --api-key YOUR_KEY --url https://your-site.com

Protokolliert jede API-Anfrage und -Antwort in stderr (Ihr API-Schlüssel wird automatisch geschwärzt) und beendet den Vorgang dann. Nützlich, wenn etwas nicht funktioniert und Sie die Ausgabe mit dem BD-Support teilen möchten.

Lassen Sie --verify weg, um den vollständigen MCP-stdio-Server mit Debug-Protokollierung zu starten — in einem normalen Terminal scheint es, als würde er hängen bleiben, da MCP-Server über stdio ewig laufen und auf einen KI-Client warten. Verwenden Sie --debug --verify für einmaliges Debugging über eine Shell.

Häufige Probleme:

401 Unauthorized — API-Schlüssel ist falsch, widerrufen oder hat keine Berechtigung für den Endpunkt
404 Not Found — Website-URL ist falsch (auf Tippfehler prüfen; https:// wird automatisch hinzugefügt, falls es fehlt)
429 Too Many Requests — Ratenlimit erreicht (Standard: 100 Anfragen/60s); warten Sie oder erhöhen Sie das Limit im BD-Adminbereich
Unknown tool (von Claude) — der MCP-Server hat die OpenAPI-Spezifikation nicht geladen; installieren Sie sie erneut mit npm install -g brilliant-directories-mcp

Authentifizierung

Alle Anfragen erfordern den X-Api-Key-Header:

X-Api-Key: your-api-key-here

API-Schlüssel sind berechtigungsbasiert — Sie steuern, auf welche Endpunkte jeder Schlüssel zugreifen kann.

Ratenlimits

Standard: 100 Anfragen pro 60 Sekunden pro API-Schlüssel. Auf Anfrage: bis zu 1.000 Anfragen pro Minute — kontaktieren Sie das Support-Team von Brilliant Directories, um das Limit Ihrer Website erhöhen zu lassen (jeder Wert zwischen 100 und 1.000/Min).

Das Limit wird serverseitig von BD festgelegt, nicht über eine Self-Service-Einstellung in Ihrem Adminbereich. Wenn Sie eine hohe API-Auslastung erwarten, senden Sie vor Massenvorgängen eine E-Mail an den BD-Support und bitten Sie um eine vorübergehende oder dauerhafte Erhöhung.

Bei Überschreitung gibt die API HTTP 429 Too Many Requests zurück. Der MCP-Server zeigt dies als umsetzbaren Fehler für Ihren KI-Agenten an — er weiß dann, dass er pausieren oder eine Erhöhung des Limits empfehlen muss.

Planung von Massenvorgängen: Wenn Sie Ihren Agenten bitten, Hunderte von Datensätzen zu importieren/aktualisieren, (a) fordern Sie zuerst eine Erhöhung des Limits beim BD-Support an oder (b) weisen Sie den Agenten an, das Tempo zu drosseln (z. B. "importiere diese 500 Mitglieder und pausiere, um das Ratenlimit von 100/Min einzuhalten").

Paginierung

Alle Listen-Endpunkte unterstützen Paginierung:

Parameter	Beschreibung
`limit`	Datensätze pro Seite (Standard 25, max 100)
`page`	Cursor-Token von `next_page` aus der vorherigen Antwort

Die Antwort enthält: total, current_page, total_pages, next_page, prev_page

Filterung

Alle Listen-Endpunkte unterstützen Filterung:

GET /api/v2/user/get?property=city&property_value=Los Angeles&property_operator==

Mehrere Filter:

GET /api/v2/user/get?property[]=city&property_value[]=Los Angeles&property[]=state_code&property_value[]=CA

Operatoren: =, LIKE, >, <, >=, `<=

Sortierung

GET /api/v2/user/get?order_column=last_name&order_type=ASC

Verfügbare Ressourcen

Ressource	Basispfad	Operationen
Benutzer/Mitglieder	`/api/v2/user/`	list, get, create, update, delete, search, login, transactions, subscriptions
Bewertungen	`/api/v2/users_reviews/`	list, get, create, update, delete, search
Klicks	`/api/v2/users_clicks/`	list, get, create, update, delete
Leads	`/api/v2/leads/`	list, get, create, match, update, delete
Lead-Matches	`/api/v2/lead_matches/`	list, get, create, update, delete
Beiträge	`/api/v2/data_posts/`	list, get, create, update, delete, search, fields
Portfolio-Gruppen	`/api/v2/users_portfolio_groups/`	list, get, create, update, delete, search, fields
Portfolio-Fotos	`/api/v2/users_portfolio/`	list, get, create, update, delete
Beitragstypen	`/api/v2/data_categories/`	list, get, create, update, delete, custom_fields
Kategorien	`/api/v2/category/`	list, get, create, update, delete
Kategorie-Gruppen	`/api/v2/category_group/`	list, get, create, update, delete
Dienste	`/api/v2/list_services/`	list, get, create, update, delete
Benutzer-Dienste	`/api/v2/rel_services/`	list, get, create, update, delete
Benutzer-Fotos	`/api/v2/users_photo/`	list, get, create, update, delete
Benutzer-Metadaten	`/api/v2/users_meta/`	list, get, create, update, delete
Tags	`/api/v2/tags/`	list, get, create, update, delete
Tag-Gruppen	`/api/v2/tag_groups/`	list, get, create, update, delete
Tag-Typen	`/api/v2/tag_types/`	list, get, create, update, delete
Tag-Beziehungen	`/api/v2/rel_tags/`	list, get, create, update, delete
Widgets	`/api/v2/data_widgets/`	list, get, create, update, delete, render
E-Mail-Vorlagen	`/api/v2/email_templates/`	list, get, create, update, delete
Formulare	`/api/v2/form/`	list, get, create, update, delete
Formularfelder	`/api/v2/form_fields/`	list, get, create, update, delete
Mitgliedschaftspläne	`/api/v2/subscription_types/`	list, get, create, update, delete
Menüs	`/api/v2/menus/`	list, get, create, update, delete
Menüpunkte	`/api/v2/menu_items/`	list, get, create, update, delete
Abbestellen	`/api/v2/unsubscribe_list/`	list, get, create, update, delete
Smart Lists	`/api/v2/smart_lists/`	list, get, create, update, delete
Seiten (SEO/statisch)	`/api/v2/list_seo/`	list, get, create, update, delete
Weiterleitungen (301)	`/api/v2/redirect_301/`	list, get, create, update, delete
Datentypen	`/api/v2/data_types/`	list, get, create, update, delete
Website-Einstellungen	`/api/v2/website_settings/`	refreshCache

Feld-Erkennung

Einige Endpunkte unterstützen dynamische Feld-Erkennung:

# Get all available user fields
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/user/fields

# Get custom fields for a specific post type
curl -H "X-Api-Key: YOUR_KEY" https://your-site.com/api/v2/data_posts/fields?form_name=my-form

Dateien

Datei	Zweck
`openapi/bd-api.json`	OpenAPI 3.1 Spezifikation (Single Source of Truth)
`mcp/index.js`	MCP-Server für Claude/Cursor
`mcp/package.json`	npm-Paketdefinition
`docs/*.md`	Dokumentation der API-Endpunkte
`LICENSE`	MIT-Lizenz
`CHANGELOG.md`	Release-Historie

Stabile Asset-URLs

Für Tools, die Spezifikationen per URL importieren (ChatGPT Actions, n8n, Postman):

https://raw.githubusercontent.com/brilliantdirectories/brilliant-directories-mcp/main/openapi/bd-api.json

Sicherheit

API-Schlüssel werden niemals im Paket eingebettet
Alle Anfragen gehen direkt vom Computer des Benutzers an seine BD-Website
Es fließen keine Daten über Server von Drittanbietern
API-Schlüssel-Berechtigungen steuern, welche Endpunkte zugänglich sind
Behandeln Sie Ihren API-Schlüssel wie ein Passwort

Support

BD-Support: https://support.brilliantdirectories.com
API-Dokumentation: https://support.brilliantdirectories.com/support/solutions/articles/12000108045

brilliant-directories-mcp