SSyncDev

Tapir MCP Server

Gives an AI agent eyes and hands on a live Flutter app: Semantics snapshots, real taps and typing, screenshots and profiling.

Local server

What is the Tapir MCP Server?

A screenshot dragged into a chat window tells an assistant very little about why a button ignores taps. Tapir gives the agent the app's Semantics tree instead, plus the ability to act on it. Tapping, typing, scrolling and screenshotting all happen against the live app, with no test file written between actions. Its tools are served through dowel, so the Tapir MCP server appears in your client under the dowel key.

Refs, not coordinates

tapir_snap returns the tree as short labelled lines, each carrying a ref such as e2. The agent acts on refs rather than pixel positions. A node keeps its ref across snapshots; if its widget disappears, tapir relocates it by label only when that is unambiguous, otherwise it reports the ref as defunct and the agent re-snaps. Handles minted by find or observe (q1, q2 and so on) are re-resolved against the live tree on every action and survive rebuilds. Filters like --interactiveOnly, --within and --grep keep snapshots small, which saves context.

The actionability gate

Before a tap or a fill lands, tapir runs a fixed series of checks. Each refusal starts with a stable phrase an agent can branch on:

  • defunct when the ref no longer exists
  • not enabled for disabled controls
  • zero rect and off-viewport for things that are not visible
  • not stable while an animation is still moving
  • obscured by when an overlay would swallow the event

A green result means the event was dispatched, not that the widget reacted. Agents should read the effect block of the response to confirm.

Waiting, screenshots and performance

There are verbs to wait for text or network idle, list routes, read console output and exceptions, take JPEG or PNG screenshots of the viewport or one widget, emulate device presets on Chrome, and bracket an interaction with performance tracing. tapir_hot_reload_and_snap reloads and returns a snapshot, screenshot and recent errors in one round trip.

Setup in brief

Run flutter pub add tapir and dart run tapir tapir:install, which adds TapirPlugin.install() behind an !kReleaseMode guard. Start the app with dart run tapir start --device=macos (or another device), then dart run tapir mcp:install to write the client entry. Requires Dart 3.13 and Flutter 3.47.

Caveats

Keep the release guard when you deploy the Tapir MCP server; anyone reaching the VM Service of a build that carries tapir can drive the app. On web, the tapir_screenshot tool can time out under CanvasKit, so the CLI path through a CDP port is the safer choice there. Hot-reload-and-snap needs a POSIX host.

Pair it with Flutter Inspector or the iOS Simulator server, or browse more mobile development tools.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

ToolWhat it does
tapir_snapSnapshot the Semantics tree with refs for each node.
tapir_tapTap a widget by ref after the actionability gate.
tapir_screenshotScreenshot the viewport or a single widget.
tapir_evaluateEvaluate an expression in the running app (not available in --cdp-port sessions).
tapir_hot_reload_and_snapHot reload, then return a snapshot, screenshot and recent exceptions (POSIX host only).

How to install the Tapir MCP Server

{
  "mcpServers": {
    "dowel": {
      "command": "./bin/dowel",
      "args": [
        "mcp:serve"
      ],
      "cwd": "."
    }
  }
}

Tapir's tools ride on the dowel server. Run dart run tapir mcp:install in the Flutter project first; on Windows or without ./bin/dowel the entry is dart run tapir mcp:serve.

Frequently asked questions

No. Tapir drives the running app over the VM Service from a CLI and MCP tools, with no flutter_test harness or test file.