ecobrowser MCP server
This server gives AI agents structured, verifiable control over web browsing through 13 tools:
Navigate & Session:
browser_navigateto open URLs,browser_backto go back in history,browser_resetto discard a crashed/stuck session and start fresh.Structured Perception:
browser_snapshotreturns all interactive elements with stable, addressable IDs;browser_changesgives only the delta since the last snapshot (token-efficient);browser_findlocates elements by natural language description (e.g. "search box", "Sign in button").Content Extraction:
browser_read_textfor visible page text,browser_extract_linksfor all links as name/href pairs.Verified Actions:
browser_clickandbrowser_typeoperate by stable element ID, with success verification and self-healing if the element has moved.Debugging & Monitoring:
browser_consolefor logs and page errors,browser_networkfor captured HTTP responses (status, method, URL).JavaScript Execution:
browser_evaluateruns arbitrary JS expressions in the page context and returns JSON-serialized results.Live Supervision: Provides a live view (screenshot + action trace) for humans to monitor headless browser operations.
Configurability: Supports environment variables to configure headless mode, live-view port, and local file access.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ecobrowser MCP serveropen github.com and search for ecobrowser"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π ecobrowser β AI-Native Browser Framework
The AI's hands and eyes on the web
A browser built to be driven by an AI β the perception and action layer that gives an agent
fast, complete, verifiable control of the web. Ships on npm as ecobrowser: a TypeScript library and an MCP server in one package.
Structured (no-pixel) perception Β· verified self-healing actions Β· incremental diff perception Β· a live view to watch it work.
Table of contents
Related MCP server: Playwright MCP Server
What is this?
Most "AI browsers" are one of two things: a chat sidebar bolted onto a browser, or a headless scraping API with no feedback loop. This is neither. It's the layer that makes a real browser usable by a model β the primary "user" is an AI, and a human just supervises.
It gives an agent a compact, structured view of a page (an addressable list of interactive elements, not a screenshot), lets it act on those elements by stable id, tells it whether each action actually worked, and streams the whole thing to a live view a human can watch. It's model-agnostic and downloadable β not tied to one vendor's extension.
The design principle, everywhere: do work in code so the model doesn't spend tokens and reasoning on it β verifying outcomes, diffing pages, recovering from failures, finding elements.
β οΈ Scope & honesty. This is a fast, local, single-user developer tool, built to be pointed at your own or authorized sites. It's young β thoroughly tested on its own paths, but not battle-hardened across thousands of real websites the way mature tools are. See Security & scope.
β¨ Highlights
ποΈ Structured perception | The AI sees a compact list of interactive elements with stable ids β no screenshotβvision round-trip. |
π― Act by id | Click/type/select by |
β Verified actions | Every action returns did it work and did the page change β success / silent no-op / failure, not a guess. |
π©Ή Self-healing | If an element's id moved (page re-rendered), it re-locates the element by identity and retries. |
π Durable ids | An element keeps its id across snapshots, so the AI can reference something it saw steps ago. |
β‘ Incremental perception |
|
π | Ask for "the search box" and get just the match β not a whole-page dump. |
π First-class debugging | Console logs, page errors, and network requests captured β errors scoped to the action that caused them. |
π₯οΈ Live view | Watch a headless run in your browser β refreshing screenshot + colour-coded action trace. |
π MCP + npm | One engine, two front doors: an MCP server (zero-code) and a typed TypeScript library. |
π Architecture
flowchart TD
AI["π€ AI client<br/>Claude Desktop Β· Cursor Β· your agent"]
MCP["<b>mcp.ts</b><br/>MCP server Β· 13 tools"]
LIVE["<b>live.ts</b><br/>live-view server"]
ENGINE["<b>browser.ts</b><br/>AIBrowser / AIPage<br/><i>the whole product</i>"]
CHROME["Chromium<br/>(headless by default)"]
HUMAN["π§ human<br/>watches & supervises"]
AI -- "JSON-RPC 2.0 / stdio" --> MCP
MCP -- "method calls" --> ENGINE
ENGINE -- "Chrome DevTools Protocol" --> CHROME
ENGINE -- "events + frames" --> LIVE
LIVE -- "screenshot + action trace" --> HUMAN
classDef eng fill:#6E56CF,stroke:#4C3A9E,color:#fff;
classDef srv fill:#1e2a3a,stroke:#89b4fa,color:#cdd6f4;
class ENGINE eng;
class MCP,LIVE srv;One engine, two front doors. All the real logic lives in browser.ts. mcp.ts is a thin adapter that exposes the engine's methods as protocol tools; live.ts is a read-only window for a human. The same engine could be wrapped as a CLI or REST API β MCP is just one adapter.
π§ How it works
Perception β action β verification
flowchart LR
A["act by id<br/>(click / type / select)"] --> B{"element<br/>found?"}
B -- yes --> C["smart-wait<br/>+ act"]
B -- "no Β· id moved" --> H["π©Ή self-heal:<br/>re-locate by identity"]
H --> C
C --> D{"effect<br/>verified?"}
D -- yes --> OK["β
ActionResult<br/>ok Β· changed?"]
D -- "no Β· error" --> R{"retries<br/>left?"}
R -- yes --> C
R -- no --> F["β οΈ ActionResult<br/>fail + heal hint"]
classDef ok fill:#1e3a2e,stroke:#a6e3a1,color:#a6e3a1;
classDef bad fill:#3a1e26,stroke:#f38ba8,color:#f38ba8;
class OK ok;
class F bad;Perception runs a script inside the page that collects interactive elements, stamps each with a durable data-ai-id, and captures role / name / value / state. A MutationObserver tracks a DOM version, so unchanged snapshots are served from cache and changes() can return just the delta.
The MCP conversation
sequenceDiagram
participant AI as π€ AI client
participant S as mcp.ts (server)
participant E as browser.ts (engine)
AI->>S: initialize
S-->>AI: capabilities
AI->>S: tools/list
S-->>AI: 13 tools + JSON schemas
Note over AI: the model now knows what it can do
AI->>S: tools/call Β· browser_navigate {url}
S->>E: goto() + snapshot()
E-->>S: structured elements
S-->>AI: content:[ text ]
AI->>S: tools/call Β· browser_click {id}
S->>E: clickById() β verify β heal
E-->>S: ActionResult + delta
S-->>AI: content:[ text ]It's an MCP server because it registers schema-typed tools and answers initialize / tools/list / tools/call as JSON-RPC 2.0 over stdio β the browser control is just what those tools happen to do.
π Quick start
Prerequisites: Node.js 18+.
npm install ecobrowserChromium is downloaded automatically on install (a postinstall hook). If you
install with --ignore-scripts, fetch it manually: npx playwright install chromium.
Option A β as an MCP server (drive it from an AI)
Claude Desktop β add to claude_desktop_config.json:
{
"mcpServers": {
"ecobrowser": {
"command": "npx",
"args": ["-y", "ecobrowser-mcp"],
"env": { "AI_BROWSER_HEADED": "1" }
}
}
}Claude Code:
claude mcp add ecobrowser -- npx -y ecobrowser-mcpRestart the client, then just ask: "navigate to example.com and list the links."
Run npx ecobrowser-mcp --help for setup, the full tool list, and environment variables.
(Working from a clone instead of the published package? Point the client at the source directly: npx tsx <repo>/src/mcp.ts.)
Option B β as a TypeScript library
import { AIBrowser } from "ecobrowser";
const browser = await AIBrowser.launch({ headless: true });
const page = await browser.newPage();
await page.goto("https://example.com");
const snap = await page.snapshot(); // { url, title, elements: [{ id, tag, role, name, value?, state? }] }
const [search] = await page.find("search box");
const result = await page.clickById(snap.elements[0].id);
console.log(result.detail); // "click e0 succeeded (page changed)."
const diff = await page.changes(); // { added, removed, changed, unchanged }
console.log(page.console(), page.network()); // first-class debugging
await browser.close();π§° MCP tools
The server exposes 13 tools; an MCP client discovers them (name + JSON schema) via tools/list.
Tool | What it does |
| Open a URL, return a structured snapshot. |
| Structured snapshot of the current page (cached until it changes). |
| Only what changed since your last snapshot β cheap re-perception. |
| Find interactive elements matching a description; get just the matches. |
| Visible text of the page. |
| Go back in history. |
| Click an element by id (verified, self-healing); returns the delta. |
| Type into a field by id (verifies the value landed). |
| Console logs + page errors on the current page. |
| Network responses (status, method, url). |
| Run a JS expression in the page, return the result. |
| All links as name/href pairs. |
| Discard the session; the next action starts fresh (crash recovery). |
π How it compares (measured)
Head-to-head vs Playwright MCP on the same page (npm run bench), measuring bytes returned to the model and tool latency.
Full page snapshot β smaller is better
This framework ββββββββββββββββββββββββ 41 KB (~10K tokens)
Playwright MCP ββββββββββββββββββββββββ 128 KB (~32K tokens)Re-perceive latency β smaller is better
This framework β 5 ms (cache hit)
Playwright MCP ββββββββββββββββββββββββ 150 ms (re-serializes every time)Incremental re-perceive after an action
This framework β delta only (bytes)
Playwright MCP ββββββββββββββββββββββββ full page again (no diff primitive)Honest caveats. This measures perception payload + tool latency, not end-to-end LLM wall-clock (no live model ran). Part of the size gap is scope β we capture interactive elements only, Playwright MCP captures the full accessibility tree. And we're faster than Playwright MCP (the wrapper), not Playwright (the shared engine under both) β the wins are caching, diffing, and a leaner format, all ideas a competitor could adopt.
βοΈ Configuration
Env var | Effect |
| Show the native browser window (default: headless). |
| Disable the live-view server. |
| Preferred live-view port (default |
| Allow |
Live view: when the MCP server starts it also serves a loopback-only page (default http://localhost:7333) β a refreshing screenshot plus a colour-coded action trace β so you can watch a headless run.
π Scripts
npm test # unit tests (diff, find, state, url-guard) β no browser needed
npm run build # compile the publishable package to dist/ (library + MCP bin)
npm run typecheck # tsc --noEmit over everything, dev scripts included
npm run demo # exercises the engine directly (headed; AI_BROWSER_HEADED=0 for headless)
npm run smoke # spawns the MCP server as a real MCP client and drives it
npm run live # starts the live view and verifies its endpoints
npm run bench # head-to-head vs Playwright MCP
npm run mcp # run the MCP server on stdioBenchmark note: Playwright MCP is a
devDependency; install its browser once withnpx @playwright/mcp install-browser chrome-for-testingbeforenpm run bench.
π Project layout
src/
index.ts # public package entry β re-exports the engine + LiveView
browser.ts # the core engine β AIBrowser / AIPage (this is the whole product)
mcp.ts # MCP server: registers the engine's methods as 13 tools (the ecobrowser-mcp bin)
live.ts # live-view server (screenshot + action trace)
demo.ts # in-code engine demo (5 parts, incl. self-healing)
mcp-smoke.ts # end-to-end MCP client test
live-smoke.ts # live-view endpoint test
bench-h2h.ts # head-to-head benchmark vs Playwright MCP
test.ts # unit tests for the pure logic
tsconfig.build.json # build config β compiles only the public surface to dist/
SPEC.md # full technical specification, north star, roadmapOnly dist/ (plus README, SPEC, LICENSE) ships in the npm tarball β the dev scripts stay in the repo.
π Security & scope
Because it's a downloadable tool you run yourself, how it's used is your responsibility. Built-in guards:
Loopback-only live view β never exposed to the LAN; the trace is rendered XSS-safely (
textContent, neverinnerHTML).Navigation guard β
file://,chrome://,javascript:and other privileged schemes blocked by default (AI_BROWSER_ALLOW_LOCAL=1to opt out).Bounded & recoverable β capped logs, per-tool timeouts, automatic crash recovery, graceful shutdown, port fallback.
Deliberately not in scope: multi-tenant hosting, auth/session isolation between users, or sandboxing browser_evaluate (which runs arbitrary JS in the page β appropriate only for sites you trust). Point it at your own or authorized sites.
πΊ Roadmap
flowchart LR
M0["M0 Β· spike"] --> M1["M1 Β· engine"] --> REL["reliability<br/>+ self-heal"] --> M3["M3 Β· MCP"] --> M4["M4 Β· speed"] --> M5["M5 Β· live view"] --> AIF["AI-friendliness"] --> HARD["hardening"] --> M2["M2 Β· npm<br/>package"] --> M6["M6 Β· auth/proxy<br/>(BYO) π¦ next"]
classDef done fill:#1e3a2e,stroke:#a6e3a1,color:#a6e3a1;
classDef next fill:#3a2e1e,stroke:#f9e2af,color:#f9e2af;
class M0,M1,REL,M3,M4,M5,AIF,HARD,M2 done;
class M6 next;Built and tested: the engine, reliability + self-healing, the MCP server, caching + diff perception, the live view, the AI-friendliness pass, the hardening pass, and the npm package (ecobrowser, with the ecobrowser-mcp bin).
Next β M6: opt-in, BYO-key auth/proxy/CAPTCHA for authorized sites.
See SPEC.md for the full specification and north star.
π€ Author
Built by Haidar Esber β Lebanese software & web developer based in France.
Available Tools
13 toolsbrowser_backA
Go back in the browser history.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the basic function. It does not disclose behavioral traits such as what happens if no history exists, whether it preserves scroll position, or if it triggers page reloads. With no annotations, the description carries the full burden but adds minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single sentence with no wasted words. It is front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description is adequate but misses some contextual details like error states (e.g., no history to go back to) or interaction with other browser tools. It meets the minimum viable but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description doesn't need to add paramenter meaning. Baseline for 0 parameters is 4. The description is sufficient for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: going back in browser history. It specifies the resource (browser history) and distinguishes from siblings like browser_navigate (which goes to a specific URL) and browser_reset (which resets state).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives like browser_navigate or browser_forward, nor does it indicate when not to use it (e.g., if there is no history).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_changesA
Return ONLY what changed since your last snapshot (added/removed/changed elements). Cheaper than a full snapshot β prefer this after an action.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses return of diffs and cost benefit, but does not mention side effects like snapshot state reset or read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences with no wasted words. Action and key differentiator front-loaded, cost hint follows.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate given no output schema and no annotations. Describes return type, compares to sibling, and gives usage guidance. Could mention safety (read-only) but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters with 100% schema coverage; description adds value by explaining output and usage context, meeting baseline for param-free tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Return' and resource 'changed since your last snapshot', specifying added/removed/changed elements. Distinguishes from full snapshot with cost and usage preference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'prefer this after an action', guiding when to use. Implicitly contrasts with browser_snapshot for full analysis, but no explicit list of when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_clickA
Click an element by its snapshot id. Returns a fresh snapshot after the action.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Element id from a snapshot, e.g. 'e0' |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It mentions state change (click action) and return of a fresh snapshot, but lacks details on prerequisites (e.g., element visibility), error handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with essential information front-loaded. No unnecessary words or details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple click action with one parameter and no output schema, the description is nearly complete. It specifies input (id) and output (fresh snapshot), though it could mention error conditions or element visibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full description for the single parameter 'id' (e.g., 'e0'). The description adds no further meaning, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies the action (click), target (element by snapshot id), and outcome (returns fresh snapshot). It distinguishes well from sibling tools like browser_type and browser_find.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Usage is implied by the action, but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_consoleA
Return console logs and page errors captured on the current page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what it returns but does not disclose side effects, read-only behavior, or whether calling this clears the logs. For a tool that likely consumes resources, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that clearly conveys the tool's purpose without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description tells what it returns but does not specify the format (e.g., array of strings, structured objects). No output schema exists. Without annotations or context, the agent must infer return type, which is a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (vacuously). Per calibration, baseline is 4. No additional parameter info is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns console logs and page errors, which is a specific verb+resource. This distinguishes it from siblings like browser_snapshot (visual) and browser_network (network logs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like browser_network or browser_read_text. The description does not mention when it is appropriate to call this function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_evaluateA
Run a JavaScript EXPRESSION in the page and return its JSON-serialized result (e.g. document.title or [...document.links].length). Not a statement body.
| Name | Required | Description | Default |
|---|---|---|---|
| js | Yes | A JS expression to evaluate in the page |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clarifies the tool evaluates expressions (not statements) and returns JSON-serialized results. However, it does not disclose whether the expression can modify the page or what happens on errors (e.g., thrown exceptions). This is a moderate level of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with an illustrative example, efficiently conveying the core functionality without redundancy. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately mentions the return format (JSON-serialized). It covers the main use case and constraint (expression vs statement). Minor gaps include error handling and side-effect disclosure, but it is largely complete for a simple read-oriented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds context with examples of valid expressions, but the parameter description itself ('A JS expression to evaluate in the page') adds little beyond what is already stated in the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool evaluates a JavaScript expression and returns JSON-serialized results, with concrete examples like `document.title`. It distinguishes itself from statement execution by explicitly saying 'Not a statement body', which differentiates from potentially similar tools like browser_console.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading dynamic page values, but does not explicitly state when to use this tool versus siblings like browser_console (which may run statements) or browser_read_text (which reads visible text). No alternative or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_extract_linksA
Extract all links on the page as name/href pairs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It only states the basic action without disclosing important behavioral details such as whether it waits for page load, includes hidden links, or mutates state. The description is too minimal for a no-annotation context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Exceptionally concise single sentence with no wasted words. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool without output schema, the description adequately covers the functionality. It could mention edge cases like dynamic links, but it's sufficient for common use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100% trivially. The description adds value by specifying the output structure (name/href pairs), exceeding the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool extracts all links as name/href pairs, with a specific verb and resource. It distinguishes from siblings like browser_navigate and browser_click, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like browser_find or browser_read_text. The description does not mention prerequisites or contextual usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_findA
Find interactive elements matching a description (e.g. 'search box', 'Sign in button') and get just the matches with their ids β far cheaper than reading a full snapshot when you know what you want.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to look for, e.g. 'login button' |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It describes the action (find) and output (matches with ids), but omits details like whether it modifies state, searches hidden elements, or requires a loaded page. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action. It is slightly verbose due to examples and comparison, but remains efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the input, action, output, and rationale. It is sufficiently complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description. The tool description reinforces the schema with additional examples. Since the schema already provides the necessary semantics, the description adds only marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find interactive elements matching a description' and gives concrete examples ('search box', 'Sign in button'). It distinguishes from siblings by highlighting cost savings over a full snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly advises when to use this tool: 'far cheaper than reading a full snapshot when you know what you want.' It does not explicitly name alternatives or state when not to use, but the context suggests it is for targeted element discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_networkA
Return the network responses (status, method, url) captured on the current page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explains that data is 'captured on the current page', suggesting a read-only retrieval. However, it does not disclose whether all network responses are included, if data persists, or any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, and contains no wasted words or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is mostly complete. It could mention that it returns only captured responses so far, but the current description is sufficient for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description adds value by specifying what is returned (status, method, url). Per guidelines, 0 parameters baseline is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return' and the resource 'network responses' with specific details (status, method, url) and context 'captured on the current page'. It distinguishes from sibling tools like browser_console (console logs) or browser_navigate (page loading).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when network request data is needed, but does not explicitly state when to use it over alternatives or mention exclusions. No guidance on prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_read_textA
Return the visible text content of the current page (truncated).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It mentions truncation but does not specify truncation limits or whether the method is non-destructive. For a read operation, basic safety is implied but not stated, and dynamic content behavior is unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with the core action. Highly concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no output schema, and no annotations, the description is adequate but could elaborate on truncation behavior or indicate that returns plain text. Sibling tools are present but not compared. Slightly incomplete for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema has no properties), and schema description coverage is 100%. Description adds no parameter information, but baseline is 4 for zero-parameter tools since there is nothing to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns visible text content of the current page, with truncation noted. Verb 'Return' and resource 'visible text content' are specific, and 'truncated' adds an important detail. It distinguishes well from siblings like browser_snapshot or browser_find.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like browser_snapshot or browser_changes. No when-not-to-use or prerequisites are mentioned, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_resetA
Close and discard the current browser session; the next action starts a fresh one. Use to recover from a wedged or crashed page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully discloses the destructive behavior: closing and discarding the session, losing state. Mentions it starts a fresh session. No contradictions. Provides appropriate behavioral context for a reset operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each essential. First describes action, second gives use case. No extraneous words. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no parameters, and no annotations, the description fully explains the tool's purpose and behavior. Adequate for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (schema is empty with 100% coverage). For zero-parameter tools, baseline is 4. Description adds no parameter info because none needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'close and discard' and resource 'current browser session'. Distinguishes from sibling tools (browser_navigate, browser_back, etc.) which manipulate the same session rather than resetting it. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'recover from a wedged or crashed page'. Implies this is not for normal navigation or back/forward actions. Does not provide explicit when-not-to-use or alternatives, but context with sibling tools makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_snapshotA
Get a structured snapshot of the current page β each interactive element has a stable id you can act on. Cached until the page changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses caching behavior ('Cached until the page changes') which is useful. However, it does not mention that the tool is read-only, nor does it describe the format of the snapshot or any potential cost (e.g., memory or time). Since no annotations are provided, the description carries burden but is somewhat vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the purpose and then add key behavioral detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description covers the main point (snapshot with stable IDs) and adds caching info. It could be more specific about what 'structured' means, but it's sufficient for simple use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Description adds no parameter information, which is acceptable. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it gets a structured snapshot of the current page and that each interactive element has a stable ID. This distinguishes it from sibling tools like browser_read_text or browser_find.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. It implies using it before interactions to get stable IDs, but does not mention alternatives or conditions where another tool might be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
browser_typeA
Type text into a field by its snapshot id (clears the field first).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Element id from a snapshot | |
| text | Yes | Text to type |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the clearing behavior, which is key, but does not mention side effects like triggering events or requiring focus. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Essential information is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description covers the main action, target identification, and a key behavior (clearing). Minor omission: does not specify the page context (currently focused page).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds extra meaning by specifying 'by its snapshot id' and 'clears the field first', enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Type text into a field by its snapshot id' with the additional behavior 'clears the field first'. This provides a specific verb, resource, and method, effectively distinguishing from siblings like browser_click or browser_find.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for typing into a field identified by snapshot id, but does not explicitly state when to use vs alternatives or provide context on prerequisites. Sibling tools are different actions, so some guidance is implicit.
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.
13 tool updates
v0.1.1- First observed
browser_back - First observed
browser_changes - First observed
browser_click - First observed
browser_console - First observed
browser_evaluate - First observed
browser_extract_links - First observed
browser_find - First observed
browser_navigate - First observed
browser_network - First observed
browser_read_text - First observed
browser_reset - First observed
browser_snapshot - First observed
browser_type
TDQS
Each tool has a clearly distinct purpose: navigation, clicking, typing, snapshotting, finding elements, evaluating JavaScript, checking console/network, resetting, etc. Overlap is minimal (e.g., snapshot vs. changes are complementary, not ambiguous).
All tools follow the 'browser_' prefix with snake_case verb_noun pattern (e.g., browser_navigate, browser_click, browser_snapshot). The naming is uniform and predictable.
13 tools cover the core browser automation actions without being too many or too few. The count is well-scoped for the domain, providing necessary functionality without bloat.
The set covers essential browser interactions: navigation, clicking, typing, state inspection, JS evaluation, console/network monitoring, and session reset. Minor gaps exist (e.g., no explicit scrolling or screenshot), but these can be worked around via JS evaluation.
Maintenance
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
Live browser debugging for AI assistants β DOM, console, network via MCP.
- mcpOAuthcom.screenshotink
Screenshot, diff, audit and sitemap-capture any web page β 5 MCP tools for AI agents.
A paid remote MCP for AI agent browser approval MCP, built to return verdicts, receipts, usage logs,
Scrape, crawl and search the web for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Chrome browser actions like navigation, clicking, form filling, screenshots, and console/network logging via an MCP server and Chrome extension.717MIT
- FlicenseNot gradedqualityCmaintenanceEnables browser automation through the MCP protocol, allowing AI agents to control a real browser using accessibility snapshots and natural language commands.-
- AlicenseBqualityAmaintenanceProvides AI agents with a real browser environment for web automation, memory, and secure credential management through 15 MCP tools.15MIT
- AlicenseAqualityDmaintenanceMCP server providing browser automation for AI agents, enabling actions like clicking and typing, structured data extraction, content validation, multi-step task execution, and memory enrichment from web pages.883MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/HaidarESBER/ai-browser'
If you have feedback or need assistance with the MCP directory API, please join our Discord server