Skip to main content
Glama

🌐 atlas-browser-mcp

Visual web browsing for AI agents via Model Context Protocol (MCP).

PyPI version License: MIT

✨ Features

  • šŸ“ø Visual-First: Navigate the web through screenshots, not DOM parsing

  • šŸ·ļø Set-of-Mark: Interactive elements labeled with clickable [0], [1], [2]... markers

  • šŸŽ­ Humanized: Bezier curve mouse movements, natural typing rhythms

  • 🧩 CAPTCHA-Ready: Multi-click support for image selection challenges

  • šŸ›”ļø Anti-Detection: Built-in measures to avoid bot detection

Related MCP server: Browser MCP Server

šŸš€ Quick Start

Installation

pip install atlas-browser-mcp
playwright install chromium

Use with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "atlas-browser-mcp"
    }
  }
}

Then ask Claude:

"Navigate to https://news.ycombinator.com and tell me the top 3 stories"

šŸ› ļø Available Tools

Tool

Description

navigate

Go to URL, returns labeled screenshot

screenshot

Capture current page with labels

click

Click element by label ID [N]

multi_click

Click multiple elements (for CAPTCHA)

type

Type text, optionally press Enter

scroll

Scroll page up or down

šŸ“– Usage Examples

Basic Navigation

User: Go to google.com
AI: [calls navigate(url="https://google.com")]
AI: I see the Google homepage. The search box is labeled [3].

User: Search for "MCP protocol"
AI: [calls click(label_id=3)]
AI: [calls type(text="MCP protocol", submit=true)]
AI: Here are the search results...

CAPTCHA Handling

User: Select all images with traffic lights
AI: [Looking at the CAPTCHA grid]
AI: I can see traffic lights in images [2], [5], and [8].
AI: [calls multi_click(label_ids=[2, 5, 8])]

šŸ”§ Configuration

Headless Mode

For servers without display:

from atlas_browser_mcp.browser import VisualBrowser

browser = VisualBrowser(
    headless=True,   # No visible browser window
    humanize=False   # Faster, less human-like
)

Custom Viewport

browser = VisualBrowser()
browser.VIEWPORT = {"width": 1920, "height": 1080}

šŸ—ļø How It Works

  1. Navigate: Browser loads the page

  2. Inject SoM: JavaScript labels all interactive elements

  3. Screenshot: Capture the labeled page

  4. AI Sees: The screenshot shows [0], [1], [2]... on buttons, links, inputs

  5. AI Acts: "Click [5]" → Browser clicks the element at that position

  6. Repeat: New screenshot with updated labels

ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│  [0] Logo    [1] Search   [2] Menu  │
│                                     │
│  [3] Article Title                  │
│  [4] Read More                      │
│                                     │
│  [5] Subscribe    [6] Share         │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜

šŸ¤ Integration

With Cline (VS Code)

{
  "mcpServers": {
    "browser": {
      "command": "atlas-browser-mcp"
    }
  }
}

Programmatic Use

from atlas_browser_mcp.browser import VisualBrowser

browser = VisualBrowser()

# Navigate
result = browser.execute("navigate", url="https://example.com")
print(f"Page title: {result.data['title']}")
print(f"Found {result.data['element_count']} interactive elements")

# Click element [0]
result = browser.execute("click", label_id=0)

# Type in focused field
result = browser.execute("type", text="Hello world", submit=True)

# Cleanup
browser.execute("close")

šŸ“‹ Requirements

  • Python 3.10+

  • Playwright with Chromium

šŸ› Troubleshooting

"Playwright not installed"

pip install playwright
playwright install chromium

"Browser closed unexpectedly"

Try running with headless=False to see what's happening:

browser = VisualBrowser(headless=False)

Elements not being detected

Some dynamic pages need more wait time. The browser waits 1.5s after navigation, but complex SPAs may need longer.

šŸ“„ License

MIT License - see LICENSE

šŸ™ Credits

Built for Atlas, an autonomous AI agent.

Inspired by:

Available Tools

6 tools
clickC

Click on an element by its label ID (shown as [N] on the screenshot)

Inputs: label_id (required).

multi_clickB

Click multiple elements at once (useful for CAPTCHA, checkboxes, etc.)

Inputs: label_ids (required).

screenshotB

Take a screenshot of the current page with labeled elements

Inputs: no named parameters.

scrollC

Scroll the page up or down

Inputs: direction.

typeA

Type text at the current focus position

Inputs: text (required), submit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: click targets single elements, multi_click handles multiple elements, navigate loads pages, screenshot captures the current state, scroll moves the viewport, and type inputs text. The descriptions make it easy for an agent to choose the right tool for each interaction.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear, imperative verbs (click, navigate, screenshot, scroll, type) and a descriptive multi_click variant. There are no deviations in style or convention, making the set predictable and readable.

    Tool Count5/5

    With 6 tools, the server is well-scoped for browser automation, covering core interactions like navigation, clicking, typing, scrolling, and screenshot capture. Each tool earns its place without redundancy, fitting a typical range for this domain.

    Completeness4/5

    The toolset covers essential browser actions (navigation, interaction, viewing) effectively, with no obvious dead ends. A minor gap exists in more advanced interactions like hovering, drag-and-drop, or form submission, but agents can work around this using the provided tools for most common tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers