Browser-verwenden Sie MCP-Server und CLI

Projekthinweis : Diese MCP-Serverimplementierung basiert auf der Browser-/Web-UI- Grundlage. Die grundlegende Browser-Automatisierungslogik und die Konfigurationsmuster wurden aus dem ursprünglichen Projekt übernommen.

KI-gesteuerter Browser-Automatisierungsserver, der das Model Context Protocol (MCP) für die Browsersteuerung in natürlicher Sprache und Web-Recherche implementiert. Bietet außerdem CLI-Zugriff auf seine Kernfunktionen.

Merkmale

• 🧠 MCP-Integration – Vollständige Protokollimplementierung für die KI-Agentenkommunikation.

• 🌐 Browser-Automatisierung – Seitennavigation, Ausfüllen von Formularen, Elementinteraktion über natürliche Sprache (Tool „ run_browser_agent “).

• 👁️ Visuelles Verständnis – Optionale Screenshot-Analyse für sehfähige LLMs.

• 🔄 Statuspersistenz – Option zum Verwalten einer Server-Browsersitzung über mehrere MCP-Aufrufe hinweg oder zum Herstellen einer Verbindung mit dem Browser des Benutzers.

• 🔌 Multi-LLM-Unterstützung – Integriert mit OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI.

• 🔍 Deep Research Tool – Spezielles Tool für mehrstufige Webrecherche und Berichterstellung ( run_deep_research -Tool).

• ⚙️ Konfiguration von Umgebungsvariablen – Vollständig konfigurierbar über Umgebungsvariablen mithilfe eines strukturierten Pydantic-Modells.

• 🔗 CDP-Verbindung – Möglichkeit, über das Chrome DevTools-Protokoll eine Verbindung zu einer vom Benutzer gestarteten Chrome/Chromium-Instanz herzustellen und diese zu steuern.

• ⌨️ CLI-Schnittstelle – Greifen Sie zum Testen und für die Skripterstellung direkt von der Befehlszeile auf die Kernfunktionen des Agenten ( run_browser_agent , run_deep_research ) zu.

Related MCP server: Browserbase MCP Server

Schnellstart

Das Wesentliche

1. Installieren Sie UV – das raketengetriebene Python-Installationsprogramm: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Holen Sie sich Playwright-Browser (erforderlich für die Automatisierung): uvx --from mcp-server-browser-use@latest python -m playwright install

Integrationsmuster

Fügen Sie für MCP-Clients wie Claude Desktop eine Serverkonfiguration hinzu, die so einfach ist wie:

// Example 1: One-Line Latest Version (Always Fresh)
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_GOOGLE_API_KEY": "YOUR_KEY_HERE_IF_USING_GOOGLE",
        "MCP_LLM_PROVIDER": "google",
        "MCP_LLM_MODEL_NAME": "gemini-2.5-flash-preview-04-17",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}

// Example 2: Advanced Configuration with CDP
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "anthropic/claude-3.5-haiku",
        "MCP_LLM_TEMPERATURE": "0.4",

        "MCP_BROWSER_HEADLESS": "false",
        "MCP_BROWSER_WINDOW_WIDTH": "1440",
        "MCP_BROWSER_WINDOW_HEIGHT": "1080",
        "MCP_AGENT_TOOL_USE_VISION": "true",

        "MCP_RESEARCH_TOOL_SAVE_DIR": "/path/to/your/research",
        "MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS": "5",

        "MCP_PATHS_DOWNLOADS": "/path/to/your/downloads",

        "MCP_BROWSER_USE_OWN_BROWSER": "true",
        "MCP_BROWSER_CDP_URL": "http://localhost:9222",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}

// Example 3: Advanced Configuration with User Data and custom chrome path
"mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["mcp-server-browser-use@latest"],
      "env": {
        "MCP_LLM_OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        "MCP_LLM_PROVIDER": "openai",
        "MCP_LLM_MODEL_NAME": "gpt-4.1-mini",
        "MCP_LLM_TEMPERATURE": "0.2",

        "MCP_BROWSER_HEADLESS": "false",

        "MCP_BROWSER_BINARY_PATH": "/path/to/your/chrome/binary",
        "MCP_BROWSER_USER_DATA_DIR": "/path/to/your/user/data",
        "MCP_BROWSER_DISABLE_SECURITY": "true",
        "MCP_BROWSER_KEEP_OPEN": "true",
        "MCP_BROWSER_TRACE_PATH": "/path/to/your/trace",

        "MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",

        "MCP_SERVER_LOGGING_LEVEL": "DEBUG",
        "MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
      }
    }
}

// Example 4: Local Development Flow
"mcpServers": {
    "browser-use": {
      "command": "uv",
      "args": [
        "--directory",
        "/your/dev/path",
        "run",
        "mcp-server-browser-use"
      ],
      "env": {
        "MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
        "MCP_LLM_PROVIDER": "openrouter",
        "MCP_LLM_MODEL_NAME": "openai/gpt-4o-mini",
        "MCP_BROWSER_HEADLESS": "true",
      }
    }
}

Wichtigste Erkenntnis: Die besten Konfigurationen ergeben sich, wenn man einfach anfängt (Beispiel 1). Die Datei .env.example enthält alle möglichen Dials.

MCP-Tools

Dieser Server stellt die folgenden Tools über das Model Context Protocol bereit:

Synchrone Tools (Warten auf Abschluss)

1. run_browser_agent

   • Beschreibung: Führt eine Browser-Automatisierungsaufgabe basierend auf natürlichen Sprachanweisungen aus und wartet auf deren Abschluss. Verwendet Einstellungen der Umgebungsvariablen MCP_AGENT_TOOL_* , MCP_LLM_* und MCP_BROWSER_* .

   • Argumente:

     • task (Zeichenfolge, erforderlich): Die primäre Aufgabe oder das primäre Ziel.

   • Rückgabe: (Zeichenfolge) Das vom Agenten extrahierte Endergebnis oder eine Fehlermeldung. Agentenverlauf (JSON, optional GIF) wird gespeichert, wenn MCP_AGENT_TOOL_HISTORY_PATH festgelegt ist.

2. run_deep_research

   • Beschreibung: Führt eine eingehende Webrecherche zu einem Thema durch, erstellt einen Bericht und wartet auf dessen Abschluss. Verwendet die Einstellungen der Umgebungsvariablen MCP_RESEARCH_TOOL_* , MCP_LLM_* und MCP_BROWSER_* . Wenn MCP_RESEARCH_TOOL_SAVE_DIR gesetzt ist, werden die Ergebnisse in einem Unterverzeichnis gespeichert; andernfalls arbeitet der Server im Nur-Speicher-Modus.

   • Argumente:

     • research_task (Zeichenfolge, erforderlich): Das Thema oder die Frage für die Recherche.

     • max_parallel_browsers (Ganzzahl, optional): Überschreibt MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS aus der Umgebung.

   • Gibt zurück: (Zeichenfolge) Der generierte Forschungsbericht im Markdown-Format, einschließlich des Dateipfads (falls gespeichert) oder einer Fehlermeldung.

CLI-Nutzung

Dieses Paket bietet auch eine Befehlszeilenschnittstelle mcp-browser-cli für direkte Tests und Skripting.

Globale Optionen:

• --env-file PATH, -e PATH : Pfad zu einer .env Datei, aus der Konfigurationen geladen werden sollen.

• --log-level LEVEL, -l LEVEL : Überschreibt die Protokollierungsebene (z. B. DEBUG , INFO ).

Befehle:

1. mcp-browser-cli run-browser-agent [OPTIONS] TASK

   • Beschreibung: Führt eine Browser-Agent-Aufgabe aus.

   • Argumente:

     • TASK (Zeichenfolge, erforderlich): Die primäre Aufgabe für den Agenten.

   • Beispiel:

     mcp-browser-cli run-browser-agent "Go to example.com and find the title." -e .env

2. mcp-browser-cli run-deep-research [OPTIONS] RESEARCH_TASK

   • Beschreibung: Führt Deep-Web-Recherchen durch.

   • Argumente:

     • RESEARCH_TASK (Zeichenfolge, erforderlich): Das Thema oder die Frage für die Recherche.

   • Optionen:

     • --max-parallel-browsers INTEGER, -p INTEGER : Überschreibt MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS .

   • Beispiel:

     mcp-browser-cli run-deep-research "What are the latest advancements in AI-driven browser automation?" --max-parallel-browsers 5 -e .env

Alle anderen Konfigurationen (LLM-Schlüssel, Pfade, Browsereinstellungen) werden aus Umgebungsvariablen (oder der angegebenen .env Datei) übernommen, wie im Abschnitt „Konfiguration“ beschrieben.

Konfiguration (Umgebungsvariablen)

Konfigurieren Sie Server und CLI mithilfe von Umgebungsvariablen. Sie können diese in Ihrem System festlegen oder in einer .env Datei im Projektstamm speichern (verwenden Sie --env-file für die CLI). Variablen werden mit Präfixen strukturiert.

Unterstützte LLM-Anbieter ( MCP_LLM_PROVIDER ): openai , azure_openai , anthropic , google , mistral , ollama , deepseek , openrouter , alibaba , moonshot , unbound

(Eine umfassende Liste aller unterstützten Umgebungsvariablen und ihrer spezifischen Anbieterschlüssel/Endpunkte finden Sie unter .env.example .)

Verbindung zu Ihrem eigenen Browser herstellen (CDP)

Anstatt den Server seine eigene Browserinstanz starten und verwalten zu lassen, können Sie ihn mit einem Chrome/Chromium-Browser verbinden, den Sie selbst starten und verwalten.

Schritte:

1. Starten Sie Chrome/Chromium mit aktiviertem Remote-Debugging: (Befehle für macOS, Linux, Windows wie zuvor aufgeführt, z. B. google-chrome --remote-debugging-port=9222 )

2. Umgebungsvariablen konfigurieren: Legen Sie die folgenden Umgebungsvariablen fest:

   MCP_BROWSER_USE_OWN_BROWSER=true
   MCP_BROWSER_CDP_URL=http://localhost:9222 # Use the same port
   # Optional: MCP_BROWSER_USER_DATA_DIR=/path/to/your/profile

3. Führen Sie den MCP-Server oder die CLI aus: Starten Sie den Server ( uv run mcp-server-browser-use ) oder die CLI ( mcp-browser-cli ... ) wie gewohnt.

Wichtige Hinweise:

• Der mit --remote-debugging-port gestartete Browser muss geöffnet bleiben.

• Einstellungen wie MCP_BROWSER_HEADLESS und MCP_BROWSER_KEEP_OPEN werden ignoriert, wenn MCP_BROWSER_USE_OWN_BROWSER=true .

Entwicklung

# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run MCP server with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222 --user-data-dir="optional/path/to/user/profile"
# 2. Run inspector command with environment variables:
npx @modelcontextprotocol/inspector@latest \
  -e MCP_LLM_GOOGLE_API_KEY=$GOOGLE_API_KEY \
  -e MCP_LLM_PROVIDER=google \
  -e MCP_LLM_MODEL_NAME=gemini-2.5-flash-preview-04-17 \
  -e MCP_BROWSER_USE_OWN_BROWSER=true \
  -e MCP_BROWSER_CDP_URL=http://localhost:9222 \
  -e MCP_RESEARCH_TOOL_SAVE_DIR=./tmp/dev_research_output \
  uv --directory . run mcp-server-browser-use

# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

# Run CLI example
# Create a .env file with your settings (including MCP_RESEARCH_TOOL_SAVE_DIR) or use environment variables
uv run mcp-browser-cli -e .env run-browser-agent "What is the title of example.com?"
uv run mcp-browser-cli -e .env run-deep-research "What is the best material for a pan for everyday use on amateur kitchen and dishwasher?"

Fehlerbehebung

• Konfigurationsfehler beim Start : Wenn der Start der Anwendung fehlschlägt und eine Fehlermeldung über eine fehlende Einstellung angezeigt wird, stellen Sie sicher, dass alle obligatorischen Umgebungsvariablen (wie MCP_RESEARCH_TOOL_SAVE_DIR ) in Ihrer Umgebung oder .env Datei richtig eingestellt sind.

• Browserkonflikte : Wenn Sie CDP nicht verwenden ( MCP_BROWSER_USE_OWN_BROWSER=false ), stellen Sie sicher, dass keine in Konflikt stehenden Chrome-Instanzen mit demselben Benutzerdatenverzeichnis ausgeführt werden, wenn MCP_BROWSER_USER_DATA_DIR angegeben ist.

• CDP-Verbindungsprobleme : Bei Verwendung von MCP_BROWSER_USE_OWN_BROWSER=true :

  • Überprüfen Sie, ob Chrome mit --remote-debugging-port gestartet wurde.

  • Stellen Sie sicher, dass der Port in MCP_BROWSER_CDP_URL übereinstimmt.

  • Überprüfen Sie Firewalls und stellen Sie sicher, dass der Browser ausgeführt wird.

• API-Fehler : Überprüfen Sie die API-Schlüssel ( MCP_LLM_<PROVIDER>_API_KEY oder MCP_LLM_API_KEY ) und Endpunkte (z. B. MCP_LLM_AZURE_OPENAI_ENDPOINT für Azure).

• Sehprobleme : Stellen Sie sicher, MCP_AGENT_TOOL_USE_VISION=true und Ihr LLM die Sehfunktion unterstützt.

• Abhängigkeitsprobleme : Führen Sie uv sync und uv run playwright install aus.

• Datei-/Pfadprobleme :

  • Wenn optionale Funktionen wie das Speichern des Verlaufs, die Ablaufverfolgung oder Downloads nicht funktionieren, stellen Sie sicher, dass die entsprechenden Pfadvariablen ( MCP_AGENT_TOOL_HISTORY_PATH , MCP_BROWSER_TRACE_PATH , MCP_PATHS_DOWNLOADS ) festgelegt sind und die Anwendung über Schreibberechtigungen für diese Speicherorte verfügt.

  • Stellen Sie für eine gründliche Recherche sicher, dass MCP_RESEARCH_TOOL_SAVE_DIR auf ein gültiges, beschreibbares Verzeichnis eingestellt ist.

• Protokollierung : Überprüfen Sie die Protokolldatei ( MCP_SERVER_LOG_FILE , falls aktiviert) oder die Konsolenausgabe. Erhöhen Sie MCP_SERVER_LOGGING_LEVEL auf DEBUG , um weitere Details zu erhalten. Verwenden Sie für die Befehlszeilenschnittstelle --log-level DEBUG .

Lizenz

MIT – Einzelheiten finden Sie in der LIZENZ .