Blueprint MCP Server

offiziell

Browser-Automatisierung via MCP für Chrome und Firefox

Dokumentation

Blueprint MCP

Steuern Sie Ihren echten Browser mit KI über das Model Context Protocol

Was ist das?

Ein MCP (Model Context Protocol)-Server, der KI-Assistenten erlaubt, Ihren tatsächlichen Browser (Chrome, Firefox oder Opera) über eine Browser-Erweiterung zu steuern. Anders als Headless-Automatisierungstools nutzt dies Ihr echtes Browser-Profil mit all Ihren eingeloggten Sitzungen, Cookies und Erweiterungen.

Perfekt für: KI-Agenten, die mit Websites interagieren müssen, auf denen Sie bereits eingeloggt sind, oder die Bot-Erkennung vermeiden müssen.

Warum dies anstelle von Playwright/Puppeteer verwenden?

Blueprint MCP	Playwright/Puppeteer
✅ Echter Browser (nicht headless)	❌ Headless oder neue Browser-Instanz
✅ Bleibt auf all Ihren Websites eingeloggt	❌ Muss sich in jeder Sitzung neu authentifizieren
✅ Vermeidet Bot-Erkennung (nutzt echten Fingerabdruck)	⚠️ Wird oft als automatisierter Browser erkannt
✅ Funktioniert mit Ihren vorhandenen Browser-Erweiterungen	❌ Keine Erweiterungsunterstützung
✅ Keine Einrichtung – funktioniert sofort	⚠️ Erfordert Browser-Installation
✅ Chrome, Firefox, Edge, Opera-Unterstützung	✅ Chrome, Firefox, Safari-Unterstützung

Installation

1. Installieren Sie den MCP-Server

npm install -g @railsblueprint/blueprint-mcp

2. Installieren Sie die Browser-Erweiterung

Wählen Sie Ihren Browser:

Chrome / Edge / Opera

Chrome Web Store (funktioniert für alle Chromium-Browser)
Manuell: Herunterladen von Releases, dann entpackt laden unter chrome://extensions/ (Chrome), edge://extensions/ (Edge) oder opera://extensions/ (Opera)

Firefox

Firefox Add-ons
Manuell: Herunterladen von Releases, dann laden unter about:debugging#/runtime/this-firefox

3. Konfigurieren Sie Ihren MCP-Client

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Claude Code (KI-gestützte CLI):

claude mcp add browser npx @railsblueprint/blueprint-mcp@latest

VS Code / Cursor (.vscode/settings.json):

{
  "mcp.servers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Schnellstart

Starten Sie Ihren MCP-Client (Claude Desktop, Cursor usw.)
Klicken Sie auf das Blueprint MCP-Erweiterungssymbol in Ihrem Browser
Die Erweiterung verbindet sich automatisch mit dem MCP-Server
Bitten Sie Ihren KI-Assistenten zu browsen!

Beispielkonversationen:

You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*

You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*

You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*

So funktioniert es

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   (this package)        │
└───────────┬─────────────┘
            │
            │ WebSocket (localhost:5555 or cloud relay)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Browser Extension APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

Free vs PRO

Free-Tarif (Standard)

✅ Lokale WebSocket-Verbindung (Port 5555)
✅ Einzelne Browser-Instanz
✅ Alle Browser-Automatisierungsfunktionen
✅ Kein Konto erforderlich
❌ Auf denselben Rechner beschränkt

PRO-Tarif

✅ Cloud-Relay – von überall verbinden
✅ Mehrere Browser – mehrere Browser-Instanzen steuern
✅ Geteilter Zugriff – mehrere KI-Clients können denselben Browser nutzen
✅ Auto-Reconnect – hält die Verbindung bei Netzwerkänderungen aufrecht
✅ Priorisierter Support

Upgrade auf PRO

Verfügbare Tools

Der MCP-Server stellt KI-Assistenten diese Tools zur Verfügung:

Verbindungsverwaltung

enable – Browser-Automatisierung aktivieren (erforderlicher erster Schritt)
disable – Browser-Automatisierung deaktivieren
status – Verbindungsstatus prüfen
auth – Bei PRO-Konto anmelden (für Cloud-Relay-Funktionen)

Tab-Verwaltung

browser_tabs – Browser-Tabs auflisten, erstellen, anhängen oder schließen

Navigation

browser_navigate – Zu einer URL navigieren
browser_navigate_back – Im Verlauf zurückgehen

Inhalt & Inspektion

browser_snapshot – Barrierefreien Seiteninhalt abrufen (empfohlen zum Lesen von Seiten)
browser_take_screenshot – Visuellen Screenshot aufnehmen
browser_console_messages – Browser-Konsolenprotokolle abrufen
browser_network_requests – Leistungsstarkes Netzwerküberwachungs- und Wiederholungstool mit mehreren Aktionen:
- Listenmodus (Standard): Leichtgewichtige Übersicht mit Filterung und Paginierung (Standard: 20 Anfragen)
  - Filter: urlPattern (Teilzeichenkette), method (GET/POST), status (200/404), resourceType (xhr/fetch/script)
  - Paginierung: limit (Standard: 20), offset (Standard: 0)
  - Beispiel: action='list', urlPattern='api/users', method='GET', limit=10
- Detailmodus: Vollständige Anfrage-/Antwortdaten für eine bestimmte Anfrage, einschließlich Header und Body
- JSONPath-Filterung: Große JSON-Antworten mit JSONPath-Syntax abfragen (z. B. $.data.items[0])
- Wiederholungsmodus: Erfasste Anfragen mit ursprünglichen Headern und Authentifizierung erneut ausführen
- Löschmodus: Erfassten Verlauf löschen, um Speicher freizugeben
- Beispiel: action='details', requestId='12345.67', jsonPath='$.data.users[0]'
browser_extract_content – Seiteninhalt als Markdown extrahieren

Interaktion

browser_interact – Mehrere Aktionen nacheinander ausführen (Klick, Eingabe, Hover, Warten usw.)
browser_click – Auf Elemente klicken
browser_type – Text in Eingabefelder eingeben
browser_hover – Über Elemente fahren (Hover)
browser_select_option – Dropdown-Optionen auswählen
browser_fill_form – Mehrere Formularfelder auf einmal ausfüllen
browser_press_key – Tastaturtasten drücken
browser_drag – Elemente per Drag & Drop verschieben

Erweitert

browser_evaluate – JavaScript im Seitenkontext ausführen
browser_handle_dialog – Alert/Confirm/Prompt-Dialoge behandeln
browser_file_upload – Dateien über Datei-Upload-Felder hochladen
browser_window – Browserfenster vergrößern, verkleinern, minimieren, maximieren
browser_pdf_save – Aktuelle Seite als PDF speichern
browser_performance_metrics – Leistungsmetriken abrufen
browser_verify_text_visible – Überprüfen, ob Text vorhanden ist (zum Testen)
browser_verify_element_visible – Überprüfen, ob Element existiert (zum Testen)

Erweiterungsverwaltung

browser_list_extensions – Installierte Browser-Erweiterungen auflisten
browser_reload_extensions – Entpackte Erweiterungen neu laden (nützlich während der Entwicklung)

Entwicklung

Voraussetzungen

Node.js 18+
Ein unterstützter Browser (Chrome, Firefox, Edge oder Opera)
npm oder yarn

Einrichtung

# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# Install server dependencies
cd server
npm install
cd ..

# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..

Ausführung in der Entwicklung

Terminal 1: MCP-Server im Debug-Modus starten

cd server
node cli.js --debug

Terminal 2: Chrome-Erweiterung bauen

cd extensions/chrome
npm run build
# or for watch mode:
npm run dev

Hinweis: Die Firefox-Erweiterung benötigt keinen Build-Schritt – sie verwendet reines JavaScript und kann direkt aus extensions/firefox/ geladen werden

Erweiterung in Ihren Browser laden:

Für Chromium-Browser (Chrome, Edge, Opera):

Öffnen Sie chrome://extensions/ (Chrome), edge://extensions/ (Edge) oder opera://extensions/ (Opera)
Aktivieren Sie den "Entwicklermodus"
Klicken Sie auf "Entpackte Erweiterung laden"
Wählen Sie den Ordner extensions/chrome/dist

Für Firefox:

Öffnen Sie about:debugging#/runtime/this-firefox
Klicken Sie auf "Temporäres Add-on laden"
Wählen Sie eine beliebige Datei aus dem Ordner extensions/firefox

Projektstruktur

blueprint-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   ├── src/
│   │   ├── statefulBackend.js  # Connection state management
│   │   ├── unifiedBackend.js   # MCP tool implementations
│   │   ├── extensionServer.js  # WebSocket server for extension
│   │   ├── mcpConnection.js    # Proxy/relay connection handling
│   │   ├── transport.js        # Transport abstraction layer
│   │   ├── oauth.js            # OAuth2 client for PRO features
│   │   └── fileLogger.js       # Debug logging
│   └── tests/                  # Server test suites
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (TypeScript + Vite)
│   │   └── src/
│   │       ├── background.ts   # Extension service worker
│   │       ├── content-script.ts # Page content injection
│   │       └── utils/          # Utility functions
│   ├── firefox/                # Firefox extension (Vanilla JS)
│   │   └── src/
│   │       ├── background.js   # Service worker
│   │       └── content-script.js # Page injection
│   ├── shared/                 # Shared code between extensions
│   └── build-*.js              # Build scripts for each browser
├── docs/                       # Documentation
│   ├── testing/                # Test documentation
│   ├── architecture/           # Architecture docs
│   └── stores/                 # Browser store assets
└── releases/                   # Built extensions for distribution
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

Testen

# Run tests
npm test

# Run with coverage
npm run test:coverage

Dokumentation:

Manuelle Testverfahren – Umfassender Leitfaden für manuelle Tests
Funktionsspezifikation – Vollständige Funktionsdokumentation
Testfortschritt – Aktueller Stand der Testabdeckung

Konfiguration

Der Server funktioniert sofort mit sinnvollen Standardeinstellungen. Für erweiterte Konfiguration:

Umgebungsvariablen

Erstellen Sie eine .env-Datei im Projektstammverzeichnis:

# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

Befehlszeilenoptionen

blueprint-mcp --debug              # Enable verbose logging
blueprint-mcp --port 8080          # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080  # Combine options

Hinweis: Wenn Sie den Port ändern, müssen Sie die Einstellungen Ihrer Browser-Erweiterung entsprechend anpassen.

Fehlerbehebung

Erweiterung verbindet sich nicht

Überprüfen Sie, ob die Erweiterung installiert und aktiviert ist
Klicken Sie auf das Erweiterungssymbol – es sollte "Verbunden" anzeigen
Überprüfen Sie, ob der MCP-Server läuft (achten Sie auf einen Prozess auf Port 5555)
Versuchen Sie, die Erweiterung neu zu laden

"Port 5555 wird bereits verwendet"

Eine andere Instanz läuft. Sie können entweder:

Den bestehenden Prozess beenden:

lsof -ti:5555 | xargs kill -9

Einen anderen Port verwenden:

blueprint-mcp --port 8080

Browser-Tools funktionieren nicht

Stellen Sie sicher, dass Sie zuerst enable aufgerufen haben
Überprüfen Sie, ob Sie mit browser_tabs einen Tab angehängt haben
Stellen Sie sicher, dass der Tab noch existiert (nicht geschlossen wurde)

Hilfe erhalten

Mitwirken

Wir freuen uns über Beiträge! Siehe CONTRIBUTING.md für Richtlinien.

Sicherheit

Dieses Tool gibt KI-Assistenten Kontrolle über Ihren Browser. Bitte beachten Sie:

Der MCP-Server akzeptiert standardmäßig nur lokale Verbindungen (localhost:5555)
PRO-Relay-Verbindungen werden über OAuth authentifiziert
Die Erweiterung erfordert eine explizite Benutzeraktion zum Verbinden
Alle Browser-Aktionen durchlaufen das Berechtigungssystem des Browsers

Sicherheitsproblem gefunden? Bitte senden Sie eine E-Mail an [email protected], anstatt ein öffentliches Issue zu erstellen.

Danksagungen

Dieses Projekt wurde ursprünglich von Microsofts Playwright MCP-Implementierung inspiriert, wurde aber vollständig neu geschrieben, um browsererweiterungsbasierte Automatisierung anstelle von Playwright zu verwenden. Die Architektur, Implementierung und Herangehensweise sind grundlegend anders.

Hauptunterschiede:

Verwendet Browser-Erweiterungen mit DevTools-Protokoll (nicht Playwright)
Funktioniert mit echten Browser-Profilen (nicht isolierten Kontexten)
WebSocket-basierte Kommunikation (nicht CDP-Relay)
Cloud-Relay-Option für Fernzugriff
Free- und PRO-Tarifmodell
Multi-Browser-Unterstützung (Chrome, Firefox, Edge, Opera)

Wir sind dem Playwright-Team dankbar für die Pionierarbeit bei der Browser-Automatisierung über MCP.

Lizenz

Apache License 2.0 – siehe LICENSE

Mit ❤️ erstellt von Rails Blueprint

Website • GitHub • NPM