Dokumentation – Blockwerk installieren und mit deinem KI-Agenten verbinden

Voraussetzungen

WordPress 6.4 oder neuer, PHP 7.4 oder neuer
Ein Administrator-Konto (für die Einrichtung)
Ein MCP-fähiger KI-Agent: Claude Code, OpenAI Codex, Cursor, VS Code mit Copilot, Gemini CLI …
Empfohlen: ein Block-Theme wie Twenty Twenty-Five – dann kann der Agent auch Header, Footer und das globale Design steuern
Optional: WooCommerce für Shop-Funktionen

Installation

Testphase starten und blockwerk.zip herunterladen.
In WordPress unter Plugins → Installieren → Plugin hochladen die ZIP-Datei hochladen und aktivieren.
Du landest automatisch auf der Seite Blockwerk. Trage deinen Lizenzschlüssel ein und klicke auf Speichern & aktivieren.
Unter Verbindungs-Token erstellen einen Namen vergeben (z. B. „Claude Code – MacBook“) und den Token erstellen. Kopiere ihn sofort – er wird nur einmal angezeigt.

Agent verbinden

Nach dem Erstellen eines Tokens zeigt dir das Plugin die fertig ausgefüllte Konfiguration für jeden Agenten. Der Endpunkt deiner Website lautet immer:

https://deine-website.de/wp-json/blockwerk/v1/mcp

Claude-App (ohne Terminal)

In der Claude-App (Web, Desktop oder Handy) brauchst du keinen Token:

In Claude Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen öffnen.
Name „Blockwerk“ und den Endpunkt deiner Website eintragen (steht im Blockwerk-Menü unter „Claude-App“).
Auf „Verbinden“ klicken – es öffnet sich deine WordPress-Anmeldung. Einloggen und Zugriff erlauben.

Die Website muss dafür öffentlich per https erreichbar sein, denn Claude verbindet sich über das Internet. Verbundene Apps siehst und trennst du im Blockwerk-Menü in der Token-Liste. Benutzerdefinierte Connectors sind je nach Claude-Plan verfügbar.

Claude Code

claude mcp add --transport http blockwerk https://deine-website.de/wp-json/blockwerk/v1/mcp \
  --header "Authorization: Bearer bw_…"

OpenAI Codex

# ~/.codex/config.toml
[mcp_servers.blockwerk]
url = "https://deine-website.de/wp-json/blockwerk/v1/mcp"
bearer_token_env_var = "BLOCKWERK_TOKEN"

Ohne --header startet Claude Code stattdessen die WordPress-Anmeldung (in Claude Code: /mcp → Authenticate).

Cursor, VS Code, Gemini CLI, andere

Siehe Integrationen. Clients, die nur lokale (stdio-)Server unterstützen, verbindest du über npx -y mcp-remote <endpunkt> --header "Authorization:Bearer bw_…".

Mehrere Kunden-Websites? Lege pro Website einen eigenen Server-Namen an, z. B. blockwerk-mueller und blockwerk-schmidt. Dein Agent weiß dann immer, wo er arbeitet.

Erste Prompts

Du musst keine Werkzeugnamen kennen. Beschreibe einfach, was du willst:

„Gib mir einen Überblick über meine WordPress-Website.“
„Bau eine Startseite für eine Physiopraxis in Leipzig: Hero mit Terminbutton, Leistungen als Karten, Team, Öffnungszeiten, FAQ. Nutze die Farben aus unserem Logo (Petrol, Sand).“
„Gestalte Header und Footer neu: Logo links, Menü rechts, im Footer Kontakt, Öffnungszeiten und Social Links.“
„Ersetze auf der Seite ‚Leistungen‘ den dritten Abschnitt durch eine Preistabelle.“
„Stell die Startseite auf den Stand von gestern zurück.“

Für größere Aufgaben bringt Blockwerk fertige Workflows mit, die in Claude Code als Slash-Commands erscheinen:

Befehl	Macht
`/mcp__blockwerk__clone_site`	Look einer Referenz-Website übernehmen – mit eigenen Texten
`/mcp__blockwerk__landing_page`	Conversion-starke Landingpage
`/mcp__blockwerk__build_shop`	Kompletter WooCommerce-Shop

Wie Blockwerk baut

Agenten beschreiben Layouts in einem kompakten JSON-Format („sections“) – Abschnitte, Spalten, Raster, Cover, Buttons, Bilder, FAQs. Blockwerks Compiler übersetzt das in exakt das Block-Markup, das der WordPress-Editor selbst speichern würde. Ergebnis:

Keine Meldung „Dieser Block enthält unerwarteten oder ungültigen Inhalt“
Jeder Text, jedes Bild, jeder Button ist im Editor bearbeitbar
Farben und Größen nutzen die Design-Tokens des Themes – ändert dein Kunde die Palette, ändert sich die ganze Website
Externe Bilder werden automatisch in die Mediathek übernommen (mit Alt-Text)

Neue Seiten werden als Entwurf angelegt. Dein Agent schickt dir die Vorschau-Links; veröffentlicht wird erst nach deinem OK.

Werkzeuge

Eine Übersicht aller 30 Werkzeuge findest du unter Integrationen. Dein Agent sieht zu jedem Werkzeug eine ausführliche Beschreibung und wählt selbst das passende.

Sicherheit & Datenschutz

Tokens werden nur als SHA-256-Hash gespeichert und können jederzeit widerrufen werden.
Der Agent hat höchstens die Rechte des WordPress-Benutzers, der den Token erstellt hat.
Nichts wird endgültig gelöscht – nur in den Papierkorb verschoben. Jede Änderung erzeugt eine Revision.
Das Aktivitätslog (Blockwerk → Aktivität) zeigt jede Aktion mit Agent, Werkzeug und Ergebnis.
Blockwerk überträgt keine Inhalte an unsere Server – nur Lizenzschlüssel, Website-URL und Versionsnummern für die Lizenzprüfung.
Google Fonts installiert Blockwerk lokal auf deiner Website – Besucher laden nichts von Google.

Fehlerbehebung

„Unauthorized“ obwohl der Token stimmt

Manche Hoster entfernen den Authorization-Header. Lösung A: Sende den Token stattdessen als X-Blockwerk-Token: bw_…. Lösung B (Apache): in der .htaccess ergänzen:

RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

„rest_no_route“ oder 404

Prüfe, ob das Plugin aktiv ist und die REST-API erreichbar ist (/wp-json/). Sicherheits-Plugins, die die REST-API sperren, müssen den Pfad blockwerk/v1 freigeben. Bei „einfachen“ Permalinks lautet der Endpunkt /?rest_route=/blockwerk/v1/mcp.

Staging mit Passwortschutz

HTTP-Basic-Auth vor der Website blockiert den Agenten. Nimm den Endpunkt vom Passwortschutz aus oder nutze eine IP-Freigabe.

„Licence inactive“

Prüfe den Status unter Konto. Nach Ablauf der Testphase pausiert nur die Verbindung – deine Inhalte bleiben unverändert.

Bilder werden nicht importiert

Der Server muss die Bild-URL abrufen dürfen. Manche Bilddienste blockieren Server-Downloads – lade das Bild dann über deinen Agenten aus einer lokalen Datei hoch.