Skip to main content
Glama

Motorika

An MCP server (stdio) that gives an AI agent fast, reliable control of Chrome:

  • tabs, forms, clicks, keyboard, scrolling and drag;

  • uploads, downloads and JS dialogs;

  • JS evaluation, console and network inspection.

It runs headed or headless, on a dedicated persistent profile or attached to a running Chrome.

What it does

  • Multi-tab: each session has its own active tab and tab list. Launch modes act on background tabs directly, without bringing them to the front.

  • fill_form: many fields in one call, under one shared budget; when a field fails, the result lists each field as ok … or failed ….

  • batch: several steps in one call; each step's output sits under its own ## step <n>: <tool> header, and the output cap is shared fairly between the steps.

  • Actions report what changed: each action prints → lines for a navigation, a new or closed tab, a dialog, a download, a live-region alert and new console errors, and a viewport snapshot after a navigation to a new document.

  • Video: frames of a <video> as images, cross-origin iframes included (a DRM-protected or not yet decoded frame comes back black), and the cues of its text tracks; play, pause, seek and rate.

  • One agent browser for many sessions: in launch mode, several Claude sessions on the same profile share one Chrome with your logins, each with its own tabs. --isolated servers never share.

  • Headed or headless, on a persistent profile, a fresh --isolated one, or attached to your running Chrome (--cdp-endpoint, --auto-connect).

Related MCP server: Chrome MCP Bridge

Quick start

  1. Have Node >= 20 and an installed Google Chrome. Nothing to clone or build: npx fetches the motorika package from npm on first start.

  2. Register: claude mcp add motorika -s user -- npx -y motorika (headed; add --headless at the end for headless Chrome). Or as a Claude Code plugin: /plugin marketplace add X2Mobile/x2-plugins, then /plugin install motorika@x2mobile.

  3. Log in once, if the agent needs your accounts: npx motorika open https://accounts.google.com, sign in, then quit Chrome fully (Cmd+Q on macOS).

  4. Try it: ask Claude Code to open a page, search for something and summarise what it finds.

The full guide, with logging in once and the permission setup: docs/quick-start.md.

Documentation

Page

What it covers

Quick start

install, register, log in once, a first prompt, permissions

Tools

targets, errors, paging, effect lines, settle, frames, dialogs, downloads and video

Configuration

every flag and env var; launch, shared, connect and auto-connect modes

Safety

the sandbox, the agent profile, origin lists, Chrome's own traffic, Claude Code permissions

Security defaults

upload roots, written files, password and secret redaction, what is not covered

Troubleshooting

error messages and what to do about them

Development

build outputs, tests, code layout

Safety

Keep your bank, your main email and admin accounts out of the agent profile. The agent acts with no per-site permission prompts, and a prompt-injected page can try to make it use whatever the agent profile (~/.motorika/profile) is logged into. Use separate, low-privilege accounts for what the agent needs. How to block sites outright, and what else to know: docs/safety.md.

License

MIT, see LICENSE. Copyright (c) 2026 X2 Mobile.

Available Tools

22 tools
batchA

Run up to 50 tool calls sequentially in one call: steps [{tool, args}]. Each step's output is under "## step : " (images kept). stop_on_error (default true) lists the remaining steps as skipped after a failure. Over the output cap, every step keeps its header and first line and the rest is shared; a cut step ends with "… chars cut from step ". batch cannot nest.

Inputs: steps (required), stop_on_error.

clickA

Click a target (ref, "x,y", or selector). Auto-waits for the element to be visible, stable, enabled and not covered. Returns an effect summary (navigation, new tabs, dialogs, downloads, live-region announcements as → alert (not JS dialogs), console errors).

Inputs: target (required), tab, count, force, +4 more.

consoleA
Read-only

Console messages and uncaught page errors of a tab, buffered from tab creation (at most 500): "[level] hh:mm:ss.mmm message (url:line)". level error|warning (warnings and errors)|all; pattern is a substring or /regex/; clear empties the buffer after reading.

Inputs: tab, clear, level, limit, +1 more.

dialogA

Accept or dismiss the pending JS dialog (confirm, prompt, beforeunload) on a tab; text answers a prompt. Alerts are auto-accepted.

Inputs: action (required), tab, text.

dragA

Drag from one target to another with real mouse events; works for HTML5 drag-and-drop and pointer-event drags.

Inputs: to (required), from (required), tab.

evaluateA
Destructive

Run JavaScript in the page. script is an expression or a function source; a function is called with the target element (or no argument). Promises are awaited. The result is JSON (truncated); DOM elements are rendered as snapshot lines with refs. Page exceptions are returned as errors.

Inputs: script (required), tab, target.

fill_formA

Fill several fields in one call and optionally click submit (only if every field succeeded). Values: text-like fields take a string (replaced); select takes an option value or label (string[] for multiple); checkbox/switch take a boolean; radio takes true, or a label/value on any radio of the group; file inputs take path(s) inside the allowed roots; date/time/color/range take the string value. One result line per field; values are never echoed.

Inputs: fields (required), tab, submit, snapshot, +1 more.

findA
Read-only

Find elements by case-insensitive substring over accessible name, visible text (also text split across elements: the smallest element holding it), placeholder, label and value, in all frames. Exact matches first. An empty query with a role lists every element of that role. Each hit is a snapshot line with its ref, followed by a line " in ".

Inputs: query (required), tab, role, limit.

hoverA

Move the mouse over a target (reveals :hover menus and tooltips).

Inputs: target (required), tab.

networkA
Read-only

Requests of a tab (at most 1000): "r METHOD status|failed: type url ms ". Filter by pattern (substring or /regex/), type (document, fetch, xhr, script, …), failed_only (network failures and HTTP >= 400). request_id shows headers (credentials redacted) and the body (text truncated at 10k; binary shows its size).

Inputs: tab, type, limit, pattern, +2 more.

pressA

Press keys or chords in order, e.g. ["Tab"], ["Control+a"], ["Meta+Shift+K"], ["ArrowDown","Enter"]. target is focused first.

Inputs: keys (required), tab, target, snapshot.

readA
Read-only

Main content of the page (or of target) as markdown: title, headings, paragraphs, lists, links as text, simple tables. Navigation, footers, cookie banners, sidebars and ads are excluded. Long content is cut at max_chars content chars and ends with "… more chars (offset= to continue)"; pass that offset for the next page.

Inputs: tab, format, offset, target, +1 more.

screenshotA
Read-only

Screenshot of the viewport (default), the full page, or a target element. Default jpeg quality 70, long edge at most max_edge (1280). Afterwards, "x,y" targets use this image's pixel coordinates. annotate draws each visible ref label on its element (removed before returning). save writes it under /screenshots/.

Inputs: tab, save, format, target, +4 more.

scrollA

Scroll the page or a container. Without direction/to, target is scrolled into view. With direction (amount px, default 80% of the viewport/container) or to top|bottom, target is the scroll container (default the page). Reports "scrolled y=/ viewport=" and a height change (infinite scroll).

Inputs: to, tab, amount, target, +1 more.

sessionA

Browser session: status (mode, headless, browser version, profile, tabs, active tab), launch (restart with new options; tabs are not carried over, cookies persist in a persistent profile), close (close the browser in launch mode, disconnect in attach modes).

Inputs: action (required), mode, headless, isolated, +1 more.

snapshotA
Read-only

Compact accessibility snapshot of a tab: one line per element "- role "name" eN attrs", indented by nesting; iframes are inlined. interactive mode (default) lists controls, headings, landmarks, dialogs, alerts; full adds text, lists, tables, images. Page with offset (line offset) when the footer says so.

Inputs: tab, mode, scope, offset, +2 more.

tabsA

Tabs: list ("t1 "Title" url (active)"), new (optionally at url, becomes active unless background:true; returns a viewport snapshot when url is given (call snapshot for the whole page)), select (make active; brings it to the front in headed mode), close (default the active tab; the previously active tab becomes active). Tab ids are never reused; popups are registered automatically.

Inputs: action (required), tab, url, background.

typeA

Type text into a field (input, textarea, contenteditable). Replaces the value by default; append adds to it; slowly sends key-by-key events (autocomplete widgets); submit presses Enter afterwards. The typed text is never echoed.

Inputs: text (required), target (required), tab, append, +4 more.

uploadA

Upload files: target is an input[type=file] (files set directly) or an element that opens a file chooser (intercepted; no native dialog appears). Paths must resolve inside the allowed roots (cwd, output dir, ~/Downloads, ~/Desktop, ~/Documents, --allow-file-root); dot-files are refused unless --allow-hidden-files.

Inputs: paths (required), target (required), tab.

videoA

Watch videos on the page (all frames, incl. cross-origin iframes). list: one line per video (ref, frame, src, duration, time, paused, muted, volume, rate, size, readyState, text tracks). play/pause/seek(time)/set(rate, muted, volume, loop). frames: images by element screenshot, each preceded by "frame i/n @ mm:ss.ss": times=[s…] (seek each), count (default 6, evenly spaced over start..end), or every_ms + duration_ms (sample while playing); seek-based capture restores time and paused state; all-black frames (DRM) are flagged. captions: text-track cues as "mm:ss.ss-mm:ss.ss text", optional start/end window. Default target: the largest visible playing video, else the largest visible one.

Inputs: action (required), end, tab, loop, +14 more.

waitA

Wait for exactly one condition: text (appears), text_gone, target with state (visible default, hidden, attached, detached), url (substring or /regex/), load_state, or ms (unconditional, at most 30000). On timeout the error names the condition.

Inputs: ms, tab, url, text, +5 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools target clearly distinct purposes (click vs hover vs drag vs upload; console vs network vs video). A few pairs could be confused at a glance—snapshot/read/find all extract page content, and type/fill_form/press all input text—but the descriptions draw sharp boundaries (accessibility tree vs markdown vs text search; single-field vs multi-field vs key chords).

    Naming Consistency4/5

    All names are lowercase snake_case, and there is a coherent underlying convention: verbs for actions (navigate, click, scroll) and nouns for subsystem controllers (session, tabs, console, network, video). Only fill_form breaks the single-word pattern, and the verb/noun split is a minor deviation rather than a real inconsistency.

    Tool Count4/5

    22 tools is on the heavy side, but browser automation is genuinely broad and each tool maps to a real capability (video, network, console, batch are legitimate subsystems rather than filler). Slightly over-scoped but nothing feels redundant enough to remove.

    Completeness4/5

    The surface covers navigation, interaction, forms, dialogs, uploads, extraction, screenshots, network, console, media and batching—an unusually complete lifecycle for a browser agent. Minor gaps: no direct cookie/storage manipulation, no download-management tool (only reported as a click effect), and no explicit viewport/resize control outside launch options.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control and interact with a Chrome browser via MCP, providing tools for navigation, screenshots, clicking, form filling, content extraction, and tab management.
      1
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to control your installed Google Chrome through MCP or HTTP using compact text snapshots, exact pixel coordinates, and a visible cursor. It provides browser tools for navigation, clicking, typing, scrolling, tabs, forms, waiting, recording, and human handoff.
      35
      108 npm
      3
      MIT