Skip to main content
Glama
Nerd0822

botcan-mcp

by Nerd0822
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

botcan

YAML-driven browser automation and scraping. Write a recipe, run it, get extracted data plus downloaded files. Runs headless Firefox through Playwright; every run uses a fresh disposable browser profile.

Quick start (dev)

uv run python run.py src/demo/demo.yaml    # demo recipe (local demo page on :5500)

Output files land in ./output relative to where you run it.

Related MCP server: marionette-mcp

Install on other machines

From this GitHub repo directly — no registry needed:

uv tool install git+https://github.com/Nerd0822/Botcan.git     # botcan CLI + botcan-mcp on PATH
uv add "botcan @ git+https://github.com/Nerd0822/Botcan.git"    # as a dependency in a project

Pin a released tag if you want immutable installs (@v0.1.0 instead of latest commit). Then one-time per machine, fetch the browser:

uvx playwright install firefox

Use it:

botcan my_recipe.yaml my_output_dir     # prints extracted_data JSON; downloads/screenshots land in the output dir
botcan-mcp                              # the MCP server (register it in your AI app, see below)

Recipe format

Top level: open (URL — starts the browser when hit), steps (list), close (optional marker). Each step is a single-key mapping.

open: https://example.com
steps:
  - fill: {selector: "#search", value: "weather"}
  - press: {selector: "#search", key: "Enter"}
  - wait: {selector: "#results", timeout: 5000}
  - extract: {selector: "#results h3", all: true}
  - copy_link: {selector: "a.permalink", key: "permalink"}
  - screenshot: {path: "results.png", full_page: true}
  - save: {path: "results.json", format: json}
close:

Actions and required args: click(selector), check(selector), uncheck(selector), clear(selector), fill(selector, value), press(selector, key), select(selector, value), hover(selector), scroll(selector), wait(selector, timeout?), copy_link(selector, key), extract(selector, first?|all?), download(selector, path), screenshot(path, full_page?), save(path, format). Unknown actions return a listed error instead of crashing.

headless lives in src/botcan/config.py (HEADLESS = False is handy while developing: you can watch the browser; the MCP server always runs headless regardless).

Run as an MCP server

uv run botcan-mcp                          # stdio MCP server: play_recipe + play_steps

Register with your AI app (point --directory at your checkout):

# OpenCode (global for every project)
opencode mcp add botcan --global -- uv --directory <path-to-botcan> run botcan-mcp
// Claude Desktop — claude_desktop_config.json
{ "mcpServers": { "botcan": { "command": "uv", "args": ["--directory", "<path-to-botcan>", "run", "botcan-mcp"] } } }
# Claude Code
claude mcp add botcan -- uv --directory <path-to-botcan> run botcan-mcp
# Codex — ~/.codex/config.toml
[mcp_servers.botcan]
command = "uv"
args = ["--directory", "<path-to-botcan>", "run", "botcan-mcp"]

Skill (teaches models the recipe language)

~/.claude/skills/botcan/SKILL.md — read natively by Claude Code, auto-discovered by OpenCode through its ~/.claude/skills compatibility scan. One file, both apps.

This repo ships the same file at skills/botcan/SKILL.md — install it by copying (or symlinking) that directory into ~/.claude/skills/botcan/.

For claude.ai: skills are uploaded as a ZIP in Settings → Skills. Build it with:

zip -r botcan-skill.zip skills/botcan

The skill only writes recipes there — running them needs the MCP server locally (see the setup steps above), since a cloud sandbox can't drive your browser.

Available Tools

2 tools
play_recipeB

Execute a YAML recipe file: open pages, run browser steps, return extracted data.

NameRequiredDescriptionDefault
output_dirNo
recipe_pathYes

Output Schema

NameRequiredDescription
resultYes

TDQS

B3/5.0
Behavior3/5

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

With no annotations, the description carries the full behavioral burden. It discloses a workflow (open pages, run browser steps, return data), which is useful, but omits important traits: side effects of writing to output_dir, authentication needs, whether recipes can perform destructive actions, and error handling. It is better than a bare verb but still incomplete.

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?

A single sentence with zero waste, front-loading the verb and resource. It is appropriately sized for a high-level summary and avoids redundant phrasing.

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

Completeness2/5

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

Although an output schema exists (so return values need not be described), the definition is incomplete for a tool that executes arbitrary YAML recipes. It lacks usage guidance versus the sibling tool, parameter documentation (especially output_dir), and any behavioral safety context, leaving the agent under-informed for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, so the description should compensate. It implies that 'recipe_path' points to a YAML recipe file, adding minimal meaning. However, 'output_dir' is never mentioned, and no format, default behavior, or constraints are explained for either parameter.

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 states a specific verb ('Execute') and resource ('YAML recipe file'), and outlines the outcome: open pages, run browser steps, return extracted data. It is clear on its own but does not explicitly differentiate itself from the sibling tool 'play_steps', which appears to execute steps directly rather than a recipe file.

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?

No when-to-use or when-not-to-use guidance is provided. There is no mention of prerequisites (e.g., recipe format, required permissions) or alternatives such as 'play_steps'. The agent is left to infer that this tool is for recipe files while the sibling is for raw steps.

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

play_stepsC

Execute an inline YAML recipe string (agent-generated). Args mirror recipe file format.

NameRequiredDescriptionDefault
output_dirNo
recipe_yamlYes

Output Schema

NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. It says nothing about side effects of executing an arbitrary YAML recipe, required permissions, sandboxing, error behavior, or idempotency. '(agent-generated)' is the only provenance hint, which is thin for an execution tool that runs caller-supplied content.

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 short sentences, front-loaded with the action. It is efficient, though the terseness arguably costs clarity rather than earning it.

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

Completeness2/5

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

For an executor of arbitrary caller-supplied YAML with zero annotation coverage and 0% schema description coverage, the definition is under-specified. An output schema exists so return values need not be described, but the input contract and safety/behavior profile are missing.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate, and it does not. 'Args mirror recipe file format' gestures at recipe_yaml but never explains the YAML structure, required keys, or what output_dir does or where files land. Both parameters remain effectively undocumented.

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 names a specific verb and resource: 'Execute an inline YAML recipe string.' The parenthetical '(agent-generated)' adds a hint about provenance. However, it never names or contrasts with the sibling play_recipe, so the agent must infer that 'inline' is what distinguishes this tool from the file-based one.

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?

There is no explicit when-to-use guidance and no mention of the sibling play_recipe. 'Inline YAML recipe string' implicitly suggests use when no recipe file exists, but the agent is left to infer that condition rather than being told it.

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.

  1. 2 tool updatesv0.1.0
    • First observedplay_recipe
    • First observedplay_steps
Deploy Server
Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

TDQS

B3/5.0

Scored across 2 tools

Disambiguation3/5

Both tools execute YAML recipes; the only difference is file vs inline string input. Descriptions clarify the distinction, but the core action overlaps, and the names play_recipe vs play_steps could confuse an agent about which to use.

Naming Consistency5/5

Both tools follow a clear verb_noun pattern with the same verb 'play_', making the naming predictable and consistent throughout.

Tool Count3/5

Only two tools are provided, which feels thin for a recipe execution server. While both earn their place, the set is borderline minimal for the apparent scope.

Completeness3/5

The surface covers file-based and inline execution, but notable operations like recipe validation, listing available recipes, or error handling without execution are missing. Agents can work around these gaps, but they are significant.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • marionette-mcp

    aidvizhhub
    A
    license
    A
    quality
    B
    maintenance
    Enables web search and browser automation against a real, locally installed Firefox driven over its built-in Marionette TCP protocol. Exposes tools for multi-engine search, JS-rendered page text and link extraction, screenshots, cookie save/load, and arbitrary JS evaluation, with SSRF guarding, rate limiting, and untrusted-content wrapping.
    10
    MIT

  • Kamurafox

    GabrielKamura
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables Claude Code to drive a local Firefox browser: opening and managing tabs, navigating, reading page structure and text, clicking, typing, filling forms, running JavaScript, taking screenshots, and inspecting console messages and network requests. Everything runs over a local Unix socket with no network traffic, and actions are restricted to tabs explicitly placed under Claude's control.
    4 npm
    GPL 3.0

  • Kitsune

    junyeong-nero
    A
    license
    B
    quality
    A
    maintenance
    Let AI agents use the Firefox, Zen, or LibreWolf browser you already have open, with your logins, cookies, and extensions intact. No Playwright, Chromium, or WebDriver. Agents work in background tabs while you keep browsing: read pages, click, fill forms, take screenshots, and capture network traffic. A WebExtension plus a local bridge lets several agents share one browser.
    25
    2
    MIT