Browser-Use Streamable HTTP MCP Server

A high-performance MCP (Model Context Protocol) server that exposes browser-use automation capabilities via the Streamable HTTP transport.

This implementation adheres to the specific MCP protocol definition for stateless/streamable HTTP, allowing bidirectional JSON-RPC communication without requiring persistent WebSocket or long-lived standard SSE connections if not supported by the infrastructure.

Architecture

• Core Engine: browser-use
• Framework: FastAPI
• Protocol: MCP (Model Context Protocol)
• Transport: StreamableHTTPServerTransport (Native MCP Python SDK)
• Automation: Playwright (Chromium)

Getting Started

Prerequisites

• Python 3.12+
• OpenAI API Key (or other supported LLM)
• Docker (optional)

Local Setup

1. Clone and install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   playwright install chromium
   

2. Configure environment: Create a .env file:

   OPENAI_API_KEY=your_key_here
   
   # Optional Configuration
   BROWSER_LLM_PROVIDER=openai  # options: openai, anthropic, google, groq, ollama
   BROWSER_LLM_MODEL=gpt-4o
   

3. Run the server:

   python server.py
   

   The server will start on http://localhost:8000.

Configuration

The server is configured via environment variables. You can copy env.sample to .env and fill in your values.

LLM Providers

Supported providers and their required environment variables:

Provider	BROWSER_LLM_PROVIDER	Required Key
OpenAI	openai	OPENAI_API_KEY
Anthropic	anthropic	ANTHROPIC_API_KEY
Google	google	GOOGLE_API_KEY
Groq	groq	GROQ_API_KEY
DeepSeek	deepseek	DEEPSEEK_API_KEY
Ollama	ollama	(None, assumes local instance)

Server Variables

• PORT: The port to run the FastAPI server on (default: 8000).
• BROWSER_LLM_MODEL: The specific model ID to use (default: gpt-4o).

MCP Protocol Details

This server implements the Streamable HTTP transport version of MCP.

Endpoints

• POST /mcp: The primary message exchange endpoint.
• GET /mcp: The server-sent events (SSE) endpoint for notifications.

Session Management

The Streamable HTTP transport requires clients to manage a session ID:

1. Initial Request: Send a POST request to /mcp. If no x-mcp-session-id header is provided, the server will generate one and return it in the x-mcp-session-id response header.
2. Subsequent Requests: All following requests (both POST and GET) must include the x-mcp-session-id header to be routed to the correct MCP session.

Tool: browse

The server exposes a single MCP tool:

• Arguments:
  • task (string): The natural language description of what the browser should do.
• Example Usage:

  {
    "method": "call_tool",
    "params": {
      "name": "browse",
      "arguments": {
        "task": "Navigate to news.ycombinator.com and give me the top 3 headlines."
      }
    }
  }
  

Docker Deployment

Build the container:

docker build -t browser-use-mcp .

Run the container:

docker run -p 8000:8000 --env-file .env browser-use-mcp

Security Note

The browser-use agent has full control over a browser instance. Ensure this server is deployed in a secure environment and that you trust the LLM's prompts.