browser-mcp MCP Server

Session-Based Browser-Use FastMCP Server

English

A modern Model Context Protocol (MCP) server that provides advanced browser automation capabilities using the FastMCP framework. Features session-based instance management, TTL cleanup, PDF generation, file downloads, cookie management, and comprehensive browser configuration options. All browser operations are implemented via browser-use.

🎯 Key Features

Session-Based Management: Each MCP session gets its own isolated browser instance automatically
Advanced Browser Control: Full browser automation with Playwright backend (via browser-use)
PDF Generation: Convert web pages to PDF with custom formatting options
File Operations: Download/upload files, manage file system, and access all temp files
Cookie Management: Set, get, and manage browser cookies for authentication
Screenshot Capture: Take full-page, viewport, or element screenshots
Tab Management: Create, switch, and close browser tabs
Content Extraction: Extract and search page content
Session Persistence: Automatic cleanup with configurable TTL
Multi-Instance Support: Run multiple isolated browser sessions
Configurable Security: All browser security settings are configurable via API

🚀 Quick Start

Install Dependencies:

Using uv (recommended):
```
uv sync --all-extras
```

Install the Browser:

uv run playwright install --with-deps chromium

Start the Server:

Using uv (recommended):
```
uv run main.py
```

Basic Usage (Direct SessionBrowserManager):

# Direct usage without MCP protocol (for testing/development)
from browser_fastmcp_server import SessionBrowserManager, BrowserConfig
import asyncio

async def main():
    # Create session manager
    manager = SessionBrowserManager(max_instances=5, default_ttl=300)
    await manager.start_cleanup_task()
    
    # Create a new browser session
    session_id = "test_session_123"
    instance = await manager.get_or_create_session_instance(
        session_id, 
        BrowserConfig(headless=True)
    )
    
    # Navigate to a website
    browser_session = instance.browser_session
    await browser_session.navigate("https://example.com")
    
    # Get page elements
    state_summary = await browser_session.get_state_summary(cache_clickable_elements_hashes=True)
    print(f"Interactive elements: {len(state_summary.selector_map)}")
    
    # Take a screenshot
    page = await browser_session.get_current_page()
    screenshot_bytes = await page.screenshot(full_page=True)
    
    # Close session when done
    await manager.close_session(session_id)
    await manager.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

🛠️ Run Tests

Install test dependencies and run all tests:

uv run python -m pytest test_browser_workflow_test.py test_browser_fastmcp_client.py test_browser_test.py -v

🛠️ Core Tools (API)

Session Management

create_chrome_instance(headless, viewport_width, viewport_height) → Create a new browser session, returns session_id
close_instance(session_id) → Close a specific session
get_instance_info(session_id) → Get info for a session
check_browser_health(session_id) → Check the health status of a browser session and provide recovery suggestions
get_browser_status() → List all sessions
close_all_instances() → Close all sessions

Browser Configuration

set_browser_config(session_id, headless, no_sandbox, user_agent, viewport_width, viewport_height, disable_web_security) → Set browser config (restart if needed)
get_browser_config(session_id) → Get current config

Navigation & Page Control

navigate_to(session_id, url, new_tab=False) → Go to any URL (optionally in new tab)
navigate_back(session_id) / navigate_forward(session_id) → History navigation
refresh_page(session_id) → Refresh the current page
get_page_state(session_id) → List interactive elements with indices

Tab Management

get_tabs_info(session_id) → List all open tabs
switch_tab(session_id, page_id) → Switch between tabs
close_tab(session_id, page_id) → Close specific tab

Element Interaction

click_element(session_id, index) → Click element by index
click_element_by_xpath(session_id, xpath) → Click element by XPath
input_text(session_id, index, text) → Type into form fields
set_element_value(session_id, index, value) → Set input/select value directly
get_element_info(session_id, index=None, xpath=None) → Get element info (by index or xpath)
send_keys(session_id, keys) → Send keyboard shortcuts
upload_file(session_id, index, file_path) → Upload files to forms
get_dropdown_options(session_id, index) → Inspect select elements

Media & Files

take_screenshot(session_id, target=None, width=None, height=None, full_page=True, quality=90, format="png") → Capture screenshots
generate_pdf(session_id, url=None, html_content=None, output_filename=None, ...) → Save page as PDF
download_file(session_id, url, output_filename=None, timeout=30) → Download files from URLs
download_image(session_id, image_url, output_filename=None, timeout=30) → Download images specifically

Cookie & Session Management

set_cookie(session_id, name, value, domain, path, http_only, secure, same_site, expires, max_age) → Set browser cookies
get_cookies(session_id, domain=None) → Retrieve current cookies

Utilities

scroll_page(session_id, direction="down") → Scroll up/down
extract_content(session_id, query) → Extract text content
wait(seconds) → Pause execution
browser_tips() → Get automation best practices
search_bing(session_id, query) → Bing search

📚 Resources (REST-style)

browser://status → Manager and sessions status
browser://instances → All sessions info
browser://instance/{id}/page → Session page info
browser://instance/{id}/tabs → Session tabs
browser://instance/{id}/screenshots → Session screenshots
browser://instance/{id}/status → Session status (detailed)
browser://instance/{id}/files → Session temp files
browser://instance/{id}/cookies → Session cookies
browser://instance/{id}/file/{relative_path} → Read a file in session temp
browser://help → This help

🔧 Configuration

Configure the server using environment variables:

# Maximum number of concurrent browser instances
BROWSER_MAXIMUM_INSTANCES=10

# Session TTL in seconds (default: 30 minutes)
BROWSER_INSTANCE_TTL=1800

# Command execution timeout in seconds
BROWSER_EXECUTE_TIMEOUT=30

# Cleanup interval in seconds
BROWSER_CLEANUP_INTERVAL=60

📝 Prompts

Built-in prompts for common automation scenarios:

web_testing(url, test_scenario) → Web testing workflows
data_extraction(url, data_type) → Data extraction strategies
form_filling(url, form_data) → Automated form filling (returns conversation)
automation_troubleshooting() → Debugging help

🔌 MCP Integration

Using with Claude Desktop

Add to Claude Desktop Configuration:

Edit your Claude Desktop configuration file (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "browser-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/path/to/browser-mcp/browser_fastmcp_server.py"],
      "env": {
        "BROWSER_MAXIMUM_INSTANCES": "5",
        "BROWSER_INSTANCE_TTL": "1800"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server
Start Using: The browser automation tools will now be available in your Claude conversations

Using with MCP Client (Two Ways)

Method 1: Network-based MCP Client (via HTTP/SSE)

import asyncio
from mcp import ClientSession, SSEClientTransport

async def main():
    # Connect to the running server via network
    transport = SSEClientTransport("http://localhost:8000/sse")
    
    async with ClientSession(transport) as session:
        # Initialize session
        await session.initialize()
        
        # Start browser
        info = await session.call_tool("create_chrome_instance", {"headless": True})
        session_id = info["session_id"]
        
        # Navigate to website
        await session.call_tool("navigate_to", {"session_id": session_id, "url": "https://example.com"})
        
        # Take screenshot
        await session.call_tool("take_screenshot", {"session_id": session_id})
        
        # Close session
        await session.call_tool("close_instance", {"session_id": session_id})

if __name__ == "__main__":
    asyncio.run(main())

Method 2: Direct Client (No Network)

import asyncio
from fastmcp import Client
from browser_fastmcp_server import mcp as browsers_mcp

async def main():
    # Direct client connection (no network)
    client = Client(browsers_mcp)
    
    async with client:
        # Start browser
        session = await client.call_tool("create_chrome_instance", {"headless": True})
        session_id = session.data.session_id
        
        # Navigate to website
        await client.call_tool("navigate_to", {"session_id": session_id, "url": "https://example.com"})
        
        # Take screenshot
        await client.call_tool("take_screenshot", {"session_id": session_id})
        
        # Close session
        await client.call_tool("close_instance", {"session_id": session_id})

if __name__ == "__main__":
    asyncio.run(main())

🔒 Authentication

For server deployments requiring authentication, modify main.py to set an AuthProvider before startup:

Basic Authentication:

from fastmcp.auth import BasicAuth

# Add this before mcp.run()
mcp.auth = BasicAuth(username="admin", password="password")

JWT Authentication (Recommended for Production):

For more advanced authentication, we recommend using fastmcp-authentication:

from fastmcp_authentication import BearerAuthProvider

JWKS_URI = "http://localhost:8080/.well-known/jwks.json"
auth = BearerAuthProvider(
    jwks_uri=JWKS_URI,
    issuer="http://localhost:8080",
    audience="localhost:8080",
    algorithm="RS256"
)

mcp.auth = auth

💡 Use Cases

Web Testing: Automated functional, security, and performance testing
Data Scraping: Extract structured data from websites
Form Automation: Fill and submit web forms programmatically
Content Monitoring: Track changes in web content
Screenshot Documentation: Capture visual evidence for reports
PDF Generation: Convert web pages to PDF documents
Session Management: Handle authenticated workflows

🔒 Security Features

Session isolation between MCP clients
Secure cookie management with HttpOnly and Secure flags
Configurable browser security settings (CORS, sandbox, etc.)
Automatic cleanup of temporary files
TTL-based session expiration

🐳 Docker Usage

Build the image:

docker build -t browser-mcp .

Run the server (default: port 8000, SSE transport):

docker run -p 8000:8000 browser-mcp

You can override startup parameters via environment variables:

docker run -e MCP_PORT=9000 -e MCP_TRANSPORT=http -e MCP_HOST=127.0.0.1 -p 9000:9000 browser-mcp

Chinese

基于会话的浏览器自动化 FastMCP 服务器，提供先进的浏览器自动化功能，使用 FastMCP 框架构建。所有浏览器操作均通过 browser-use 实现。

🎯 核心特性

基于会话的管理: 每个 MCP 会话自动获得独立的浏览器实例
高级浏览器控制: 基于 Playwright 的完整浏览器自动化（由 browser-use 提供）
PDF 生成: 将网页转换为 PDF，支持自定义格式选项
文件操作: 下载/上传文件，管理临时文件目录
Cookie 管理: 设置、获取和管理浏览器 Cookie 用于身份验证
截图捕获: 全页面、视口或元素截图
标签页管理: 创建、切换和关闭浏览器标签页
内容提取: 提取和搜索页面内容
会话持久化: 自动清理，可配置 TTL
多实例支持: 运行多个隔离的浏览器会话
可配置安全性: 所有浏览器安全设置均可通过 API 配置

🚀 快速开始

安装依赖:

使用 uv（推荐）:
```
uv sync --all-extras
```

安装浏览器:

uv run playwright install --with-deps chromium

启动服务器:

使用 uv（推荐）:
```
uv run main.py
```

基本使用（直接使用 SessionBrowserManager）:

# 直接使用，不通过 MCP 协议（用于测试/开发）
from browser_fastmcp_server import SessionBrowserManager, BrowserConfig
import asyncio

async def main():
    # 创建会话管理器
    manager = SessionBrowserManager(max_instances=5, default_ttl=300)
    await manager.start_cleanup_task()
    
    # 创建新浏览器会话
    session_id = "test_session_123"
    instance = await manager.get_or_create_session_instance(
        session_id, 
        BrowserConfig(headless=True)
    )
    
    # 导航到网站
    browser_session = instance.browser_session
    await browser_session.navigate("https://example.com")
    
    # 获取页面元素
    state_summary = await browser_session.get_state_summary(cache_clickable_elements_hashes=True)
    print(f"交互元素: {len(state_summary.selector_map)}")
    
    # 截图
    page = await browser_session.get_current_page()
    screenshot_bytes = await page.screenshot(full_page=True)
    
    # 完成后关闭会话
    await manager.close_session(session_id)
    await manager.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

🛠️ 运行测试

安装测试依赖并运行所有测试:

uv run python -m pytest test_browser_workflow_test.py test_browser_fastmcp_client.py test_browser_test.py -v

🛠️ 核心工具（API）

会话管理

create_chrome_instance(headless, viewport_width, viewport_height) → 创建新浏览器会话，返回 session_id
close_instance(session_id) → 关闭指定会话
get_instance_info(session_id) → 获取会话信息
check_browser_health(session_id) → 检查浏览器会话的健康状态并提供恢复建议
get_browser_status() → 列出所有会话
close_all_instances() → 关闭所有会话

浏览器配置

set_browser_config(session_id, headless, no_sandbox, user_agent, viewport_width, viewport_height, disable_web_security) → 设置浏览器配置（如需重启自动重启）
get_browser_config(session_id) → 获取当前配置

导航和页面控制

navigate_to(session_id, url, new_tab=False) → 导航到 URL（可选新标签页）
navigate_back(session_id) / navigate_forward(session_id) → 历史记录导航
refresh_page(session_id) → 刷新当前页面
get_page_state(session_id) → 获取带索引的交互元素

标签页管理

get_tabs_info(session_id) → 列出所有打开的标签页
switch_tab(session_id, page_id) → 切换标签页
close_tab(session_id, page_id) → 关闭指定标签页

元素交互

click_element(session_id, index) → 按索引点击元素
click_element_by_xpath(session_id, xpath) → 按 XPath 点击元素
input_text(session_id, index, text) → 在表单字段中输入文本
set_element_value(session_id, index, value) → 直接设置输入/选择值
get_element_info(session_id, index=None, xpath=None) → 获取元素信息（按索引或 xpath）
send_keys(session_id, keys) → 发送键盘快捷键
upload_file(session_id, index, file_path) → 上传文件到表单
get_dropdown_options(session_id, index) → 检查 select 元素

媒体和文件

take_screenshot(session_id, target=None, width=None, height=None, full_page=True, quality=90, format="png") → 截图
generate_pdf(session_id, url=None, html_content=None, output_filename=None, ...) → 保存页面为 PDF
download_file(session_id, url, output_filename=None, timeout=30) → 下载文件
download_image(session_id, image_url, output_filename=None, timeout=30) → 下载图片

Cookie 和会话管理

set_cookie(session_id, name, value, domain, path, http_only, secure, same_site, expires, max_age) → 设置 Cookie
get_cookies(session_id, domain=None) → 获取当前 Cookie

实用工具

scroll_page(session_id, direction="down") → 上下滚动
extract_content(session_id, query) → 提取文本内容
wait(seconds) → 暂停执行
browser_tips() → 获取自动化最佳实践
search_bing(session_id, query) → Bing 搜索

📚 资源（REST 风格）

browser://status → 管理器和会话状态
browser://instances → 所有会话信息
browser://instance/{id}/page → 会话页面信息
browser://instance/{id}/tabs → 会话标签页
browser://instance/{id}/screenshots → 会话截图
browser://instance/{id}/status → 会话详细状态
browser://instance/{id}/files → 会话临时文件
browser://instance/{id}/cookies → 会话 Cookie
browser://instance/{id}/file/{relative_path} → 读取会话临时文件
browser://help → 帮助

🔧 配置

使用环境变量配置服务器：

# 最大并发浏览器实例数
BROWSER_MAXIMUM_INSTANCES=10

# 会话 TTL（秒）（默认：30分钟）
BROWSER_INSTANCE_TTL=1800

# 命令执行超时（秒）
BROWSER_EXECUTE_TIMEOUT=30

# 清理间隔（秒）
BROWSER_CLEANUP_INTERVAL=60

📝 提示

常见自动化场景的内置 prompt：

web_testing(url, test_scenario) → Web 测试工作流
data_extraction(url, data_type) → 数据提取策略
form_filling(url, form_data) → 自动表单填写（返回对话）
automation_troubleshooting() → 调试帮助

🔌 MCP 集成

与 Claude Desktop 一起使用

添加到 Claude Desktop 配置:

编辑 Claude Desktop 配置文件（macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）:

{
  "mcpServers": {
    "browser-mcp": {
      "command": "uv",
      "args": ["run", "fastmcp", "run", "/path/to/browser-mcp/browser_fastmcp_server.py"],
      "env": {
        "BROWSER_MAXIMUM_INSTANCES": "5",
        "BROWSER_INSTANCE_TTL": "1800"
      }
    }
  }
}

重启 Claude Desktop 以加载 MCP 服务器
开始使用: 浏览器自动化工具现在可在您的 Claude 对话中使用

与 MCP 客户端一起使用（两种方式）

方式一：基于网络的 MCP 客户端（通过 HTTP/SSE）

import asyncio
from mcp import ClientSession, SSEClientTransport

async def main():
    # 通过网络连接到运行的服务器
    transport = SSEClientTransport("http://localhost:8000/sse")
    
    async with ClientSession(transport) as session:
        # 初始化会话
        await session.initialize()
        
        # 启动浏览器
        info = await session.call_tool("create_chrome_instance", {"headless": True})
        session_id = info["session_id"]
        
        # 导航到网站
        await session.call_tool("navigate_to", {"session_id": session_id, "url": "https://example.com"})
        
        # 截图
        await session.call_tool("take_screenshot", {"session_id": session_id})
        
        # 关闭会话
        await session.call_tool("close_instance", {"session_id": session_id})

if __name__ == "__main__":
    asyncio.run(main())

方式二：直接客户端（无网络）

import asyncio
from fastmcp import Client
from browser_fastmcp_server import mcp as browsers_mcp

async def main():
    # 直接客户端连接（无网络）
    client = Client(browsers_mcp)
    
    async with client:
        # 启动浏览器
        session = await client.call_tool("create_chrome_instance", {"headless": True})
        session_id = session.data.session_id
        
        # 导航到网站
        await client.call_tool("navigate_to", {"session_id": session_id, "url": "https://example.com"})
        
        # 截图
        await client.call_tool("take_screenshot", {"session_id": session_id})
        
        # 关闭会话
        await client.call_tool("close_instance", {"session_id": session_id})

if __name__ == "__main__":
    asyncio.run(main())

🔒 身份验证

对于需要身份验证的服务器部署，在启动前修改 main.py 设置 AuthProvider：

基本身份验证:

from fastmcp.auth import BasicAuth

# 在 mcp.run() 之前添加
mcp.auth = BasicAuth(username="admin", password="password")

JWT 身份验证（生产环境推荐）:

对于更高级的身份验证，我们推荐使用 fastmcp-authentication：

from fastmcp_authentication import BearerAuthProvider

JWKS_URI = "http://localhost:8080/.well-known/jwks.json"
auth = BearerAuthProvider(
    jwks_uri=JWKS_URI,
    issuer="http://localhost:8080",
    audience="localhost:8080",
    algorithm="RS256"
)

mcp.auth = auth

💡 使用场景

Web 测试: 自动化功能、安全和性能测试
数据抓取: 从网站提取结构化数据
表单自动化: 程序化填写和提交 Web 表单
内容监控: 跟踪 Web 内容变化
截图文档: 为报告捕获视觉证据
PDF 生成: 将网页转换为 PDF 文档
会话管理: 处理身份验证工作流

🔒 安全功能

MCP 客户端之间的会话隔离
支持 HttpOnly 和 Secure 标志的安全 Cookie 管理
可配置的浏览器安全设置（CORS、沙箱等）
临时文件自动清理
基于 TTL 的会话过期

🐳 Docker 用法

构建镜像:

docker build -t browser-mcp .

运行服务（默认8000端口，SSE模式）:

docker run -p 8000:8000 browser-mcp

可通过环境变量覆盖启动参数:

docker run -e MCP_PORT=9000 -e MCP_TRANSPORT=http -e MCP_HOST=127.0.0.1 -p 9000:9000 browser-mcp

Browser-MCP Server

README Documentation

Session-Based Browser-Use FastMCP Server

English

🎯 Key Features

🚀 Quick Start

🛠️ Run Tests

🛠️ Core Tools (API)

Session Management

Browser Configuration

Navigation & Page Control

Tab Management

Element Interaction

Media & Files

Cookie & Session Management

Utilities

📚 Resources (REST-style)

🔧 Configuration

📝 Prompts

🔌 MCP Integration

Using with Claude Desktop

Using with MCP Client (Two Ways)

🔒 Authentication

💡 Use Cases

🔒 Security Features

🐳 Docker Usage

Chinese

🎯 核心特性

🚀 快速开始

🛠️ 运行测试

🛠️ 核心工具（API）

会话管理

浏览器配置

导航和页面控制

标签页管理

元素交互

媒体和文件

Cookie 和会话管理

实用工具

📚 资源（REST 风格）

🔧 配置

📝 提示

🔌 MCP 集成

与 Claude Desktop 一起使用

与 MCP 客户端一起使用（两种方式）

🔒 身份验证

💡 使用场景

🔒 安全功能

🐳 Docker 用法

Quick Install

Quick Actions

Key Features

Browser-MCP Server

README Documentation

Session-Based Browser-Use FastMCP Server

English

🎯 Key Features

🚀 Quick Start

🛠️ Run Tests

🛠️ Core Tools (API)

Session Management

Browser Configuration

Navigation & Page Control

Tab Management

Element Interaction

Media & Files

Cookie & Session Management

Utilities

📚 Resources (REST-style)

🔧 Configuration

📝 Prompts

🔌 MCP Integration

Using with Claude Desktop

Using with MCP Client (Two Ways)

🔒 Authentication

💡 Use Cases

🔒 Security Features

🐳 Docker Usage

Chinese

🎯 核心特性