Skip to main content
Glama
gzigurella

chromium-mcp

by gzigurella
OverviewSchemaRelated ServersScoreDiscussions
Python

Chromium MCP

MCP server for web fetching and automation using Chromium headless browser.

Reason behind this repository

I didn't wanna waste my "limited" tokens on Z.ai coding plan, therefore I made my own MCP to interact with the web, feel free to propose enhancements or new features.

Related MCP server: pulldown

Features

  • fetch_page: Fetch web pages and convert to markdown/HTML

  • screenshot: Take screenshots of web pages or specific elements

  • interact: Automate browser interactions (click, fill, scroll, wait)

  • extract_data: Extract structured data using CSS selectors

  • get_link: Get link information and follow redirects

Installation

From Git Repository

# Clone the repository
git clone https://github.com/gzigurella/chromium-mcp.git
cd chromium-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

# Install Chromium browser (required)
playwright install chromium

With uv (recommended)

# Clone and enter directory
git clone https://github.com/gzigurella/chromium-mcp.git
cd chromium-mcp

# Install with uv
uv pip install -e .

# Install Chromium
playwright install chromium

Integration

OpenCode

Add to your ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "chromium-fetch": {
      "type": "local",
      "command": [
        "/path/to/chromium-mcp/venv/bin/python",
        "-m",
        "chromium_mcp"
      ],
      "enabled": true
    }
  }
}

Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chromium-fetch": {
      "command": "/path/to/chromium-mcp/venv/bin/python",
      "args": ["-m", "chromium_mcp"]
    }
  }
}

Generic MCP Client

For any MCP-compatible client:

# Start the server directly
/path/to/venv/bin/python -m chromium_mcp

The server communicates via stdio using the MCP protocol.

Tools

fetch_page

Fetch a web page and return content as markdown or HTML.

Parameter

Type

Required

Default

Description

url

string

Yes

-

URL to fetch

format

string

No

"markdown"

Output format: "markdown" or "html"

timeout

integer

No

30

Timeout in seconds

wait_for

string

No

null

CSS selector to wait for

{
  "url": "https://example.com",
  "format": "markdown",
  "timeout": 30,
  "wait_for": ".main-content"
}

screenshot

Take a screenshot of a web page.

Parameter

Type

Required

Default

Description

url

string

Yes

-

URL to screenshot

format

string

No

"png"

Image format: "png" or "jpeg"

quality

integer

No

80

JPEG quality (1-100)

full_page

boolean

No

false

Capture full page

selector

string

No

null

CSS selector for element

timeout

integer

No

30

Timeout in seconds

{
  "url": "https://example.com",
  "format": "png",
  "full_page": true
}

interact

Interact with web page elements sequentially.

Parameter

Type

Required

Default

Description

url

string

Yes

-

URL to interact with

actions

array

Yes

-

List of actions

timeout

integer

No

30

Timeout in seconds

Action Types:

  • click: Click element by selector

  • fill: Fill input field

  • select: Select dropdown option

  • scroll: Scroll page

  • wait: Wait for element

{
  "url": "https://example.com/search",
  "actions": [
    {"type": "fill", "selector": "input[name='q']", "value": "test search"},
    {"type": "click", "selector": "button[type='submit']"},
    {"type": "wait", "selector": ".results", "milliseconds": 2000}
  ]
}

extract_data

Extract structured data using CSS selectors.

Parameter

Type

Required

Default

Description

url

string

Yes

-

URL to extract from

selectors

array

Yes

-

List of extraction rules

timeout

integer

No

30

Timeout in seconds

{
  "url": "https://example.com/products",
  "selectors": [
    {"name": "titles", "selector": "h2.product-title", "multiple": true},
    {"name": "prices", "selector": ".price", "multiple": true},
    {"name": "links", "selector": "a.product-link", "attribute": "href", "multiple": true}
  ]
}

get_link

Get link href and text, optionally following navigation.

Parameter

Type

Required

Default

Description

url

string

Yes

-

URL of page containing link

selector

string

Yes

-

CSS selector for anchor

click

boolean

No

false

Follow the link

timeout

integer

No

30

Timeout in seconds

{
  "url": "https://example.com",
  "selector": "a.download",
  "click": true
}

Configuration

Environment Variables

Variable

Default

Description

CHROMIUM_PATH

auto

Path to Chromium executable

HEADLESS

true

Run browser in headless mode

TIMEOUT

30

Default operation timeout

DEBUG

false

Enable debug logging

# Example
export TIMEOUT=60
export HEADLESS=false
python -m chromium_mcp

Development

Running Tests

source venv/bin/activate
pytest

# With coverage
pytest --cov=src --cov-report=html

Project Structure

chromium-mcp/
├── src/chromium_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py
│   └── tools/
│       ├── __init__.py
│       ├── fetch_page.py
│       ├── screenshot.py
│       ├── interact.py
│       ├── extract_data.py
│       └── get_link.py
├── tests/
├── pyproject.toml
└── README.md

Troubleshooting

Browser Not Found

playwright install chromium

Permission Issues (Linux)

sudo sysctl -w kernel.shmmax=268435456

Timeout Errors

export TIMEOUT=60

Security

  • file:// URLs are blocked

  • Credentials are never logged

  • Browser processes are always cleaned up

  • All operations have configurable timeouts

License

MIT

Available Tools

5 tools
extract_dataA

Extract structured data from a web page using CSS selectors. Returns JSON with extracted text content or attribute values. Supports single element, multiple elements, and attribute extraction.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to extract data from (must be http or https)
selectorsYesList of CSS selectors with extraction rules
timeoutNoTimeout in seconds (default: 30)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses that it returns JSON with text or attributes, supports multiple and attribute extraction. Does not mention error handling or timeouts, but core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff, front-loaded with core action and returns. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description mentions JSON return with text or attribute values. For a simple 3-parameter tool, this is adequate. Could briefly mention error cases or sibling differentiators.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

100% schema description coverage means the schema already explains each parameter well. The description adds no extra parameter-level detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool extracts structured data from a web page using CSS selectors, distinguishing it from siblings like fetch_page (raw content) and get_link (links). Specifies return type and capabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Does not explicitly state when to use this tool versus alternatives like fetch_page or get_link. The description implies it's for selective extraction, but no direct guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_pageB

Fetch a web page using Chromium headless browser and return content as markdown or HTML. Useful for reading web pages, extracting content from dynamic sites that require JavaScript rendering.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to fetch (must be http or https)
timeoutNoTimeout in seconds (default: 30)
wait_forNoOptional CSS selector to wait for before extracting content. Useful for pages that load content dynamically.
formatNoOutput format - 'markdown' (default) or 'html'markdown

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It mentions Chromium headless browser (implying resource usage) but does not cover side effects, authentication needs, rate limits, or what happens to the browser instance after use. This is insufficient for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences are concise and front-load the core action and utility. No unnecessary information, though a slightly more structured format (e.g., mentioning intended use) could improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description hints at return format and browser usage but lacks details on error behavior, timeouts beyond parameter, or handling of network failures. Given no output schema, more completeness would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all 4 parameters well. The description adds minimal value beyond confirming output format ('markdown' or 'html'), which is already in the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches a web page using Chromium and returns content in markdown or HTML, with specific mention of dynamic sites requiring JavaScript rendering. It distinguishes from siblings like screenshot or interact, but does not explicitly contrast with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates usefulness for dynamic sites but lacks explicit when-not-to-use guidance or comparison with sibling tools (e.g., when to use fetch_page vs extract_data). No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

interactA

Interact with web page elements using Chromium headless browser. Execute actions like click, fill, select, scroll, and wait in sequence. Returns the final page content as markdown after all actions are executed.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to interact with (must be http or https)
actionsYesList of actions to execute in sequence
timeoutNoTimeout in seconds (default: 30)

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses that the tool returns markdown after all actions, which is behavioral. However, it lacks details on error handling (e.g., if a selector fails), timeouts, or any side effects. Still, the core behavior is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose and technology, second lists actions and output. Front-loaded with key information, no fluff. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description provides the return format (markdown). The tool has three parameters with full schema descriptions, and siblings are distinct. The description is sufficient for an agent to understand the tool's role and how to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline 3. The description adds meaning by stating that actions are executed in sequence and that the final result is markdown, which the schema lacks (no output schema). However, it does not go beyond listing the same action types already in the enum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: interacting with web page elements via a Chromium headless browser, executing actions like click, fill, select, scroll, and wait in sequence, and returning the final page content as markdown. This distinguishes it from siblings like fetch_page (raw fetch) or extract_data (likely extraction), making it specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for interactive sequences but does not explicitly state when to use this tool versus alternatives (e.g., when no interaction is needed, use fetch_page). No when-not-to-use or alternative tool names are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screenshotA

Take a screenshot of a web page using Chromium headless browser. Returns base64-encoded image. Supports PNG and JPEG formats, full page screenshots, and element screenshots via CSS selector.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL to screenshot (must be http or https)
formatNoImage format - 'png' (default) or 'jpeg'png
qualityNoJPEG quality 1-100 (default: 80, only for jpeg)
full_pageNoTake full page screenshot (default: False)
selectorNoOptional CSS selector for element screenshot
timeoutNoTimeout in seconds (default: 30)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses the headless browser tech, base64 output, and supported formats. However, it omits details like error handling (e.g., page load failures) or behavior with dynamic content, but overall it provides sufficient transparency for a screenshot tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences with no wasted words. The first sentence front-loads the primary action and output format, while the second adds key variations. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema and 6 parameters, the description is fairly complete for a simple tool. It covers the main use cases (normal, full page, element). However, it does not mention error scenarios or return structure (e.g., base64 string details), which would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by grouping features (e.g., 'full page screenshots' maps to full_page, 'element screenshots via CSS selector' maps to selector). It doesn't repeat schema descriptions but provides conceptual context, earning a score above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Take a screenshot'), the resource ('a web page'), and the method ('Chromium headless browser'). It also lists supported formats and features, making the purpose unmistakable. It distinguishes from sibling tools (like fetch_page or extract_data) by focusing on visual capture.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., fetch_page for text content). It lacks explicit 'when-to-use' or 'when-not-to-use' instructions. Without this, an AI agent may incorrectly select this tool for non-visual tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observedextract_data
    • First observedfetch_page
    • First observedget_link
    • First observedinteract
    • First observedscreenshot
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: fetching full page, extracting data via selectors, getting link info, interacting with elements, and taking screenshots. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (e.g., fetch_page, extract_data, get_link, interact, screenshot). No mixing of conventions.

Tool Count5/5

5 tools is well-scoped for a browser automation server, covering the essential workflows without being excessive or insufficient.

Completeness4/5

The tool set covers core web scraping needs: fetching, extracting, interacting, and screenshots. Minor gaps exist (e.g., cookie handling, network capture), but the surface is largely complete for common use cases.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Shark-no-Kari

    HaiNick
    A
    license
    Not graded
    quality
    A
    maintenance
    Remote MCP server for web scraping with anti-bot evasion. Provides stealth HTTP fetching, headless browser with Cloudflare bypass, CSS selectors, YouTube transcripts, and Markdown conversion.
    1
    MIT

  • pulldown

    anthony-maio
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for retrieving web pages as clean Markdown, with configurable detail levels and optional Chromium rendering for JavaScript-heavy pages.
    1
    MIT

  • puppeteer

    silvino-av
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for headless browser automation using Puppeteer, enabling AI to navigate, click, fill forms, take screenshots, and execute JavaScript on web pages.
    -

  • scribe-me

    jlehman
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server to scrape web pages to clean Markdown via headless Chromium, with support for single or batch URLs.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gzigurella/chromium-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server