# Tap — Browser Automation MCP for Your Real Browser

Tap is a local-first MCP browser-automation runtime. Claude Code, Cursor, Continue, Windsurf, or any MCP-compatible AI agent can drive your real Chrome with your own logged-in sessions — no cloud credentials, no per-step LLM cost, no vendor lock-in.

AI participates at compile time only: saved plans replay deterministically at zero LLM token cost.

## Why Tap (vs. Stagehand / Browserbase / Playwright-MCP / BrowserMCP)

Every cloud-first browser-automation MCP forces a tradeoff: ship your credentials to someone else's server, OR re-run an LLM on every step ($$$). Tap takes neither:

- Runs in YOUR browser — your existing Chrome session with all your cookies, 2FA state, single-sign-on tokens. Credentials never cross a trust boundary; the extension only relays plan steps to the local Tap binary on your machine.
- Zero-token replay — the AI agent compiles a plan ONCE into an inspectable JSON artifact. Every subsequent run is pure data + dispatch. No vision loop, no accessibility-tree re-parse, no per-execution token bill.
- Plans are diff-able JSON — version-controllable, testable, shareable. Not opaque generated code, not LLM scratch-state.

## Features

- MCP-native — drop-in for any MCP-compatible host (Claude Code, Cursor, Continue, Windsurf, Cline). 4 meta verbs: capture / verify / mark / run.
- Authenticated by default — reuses your live Chrome cookies via Chrome Native Messaging. Same trust model as a browser bookmarklet; no localhost ports, no OS service.
- Compile-time AI, runtime zero AI — the AI generates the plan once; runtime is deterministic. Predictable cost, predictable behavior, reproducible failures.
- Composite plans — one plan can call other plans (op:tap composition). `tap verify` recursively checks composite plans against live substrates without side-effects.
- Open MIT-licensed community plan corpus — 80+ pre-built plans across 55+ sites covering dev platforms, social networks, financial data, and productivity apps. Browse at https://taprun.dev/taps/.
- Local-first by architecture — no cloud account, no telemetry, no license heartbeat. Every feature has a 100% local mode.

## Compared

|                                  | Tap | Stagehand | Browserbase | Playwright-MCP | BrowserMCP |
| -------------------------------- | --- | --------- | ----------- | -------------- | ---------- |
| Runs with your logged-in session | ✓   | cloud     | cloud       | partial        | ✓          |
| Zero LLM tokens on replay        | ✓   | per-step  | per-step    | per-step       | per-step   |
| Plans as inspectable JSON        | ✓   | opaque    | opaque      | vision loop    | a11y loop  |
| MCP-native                       | ✓   | partial   | partial     | ✓              | ✓          |
| Open-source plan corpus          | ✓   | —         | —           | —              | partial    |

## How It Works

This extension is the browser half of Tap. It talks to the Tap CLI on your machine via Chrome's Native Messaging transport. No code runs without the CLI.

1. Install the Tap CLI on your machine.

   # macOS (Homebrew)
   brew install LeonTing1010/tap/taprun

   # macOS / Linux (curl)
   curl -fsSL https://taprun.dev/install.sh | sh

   # any platform with Node 18+
   npx -y @taprun/cli --version

2. Install this Chrome extension from the Chrome Web Store.

3. Register the native-messaging manifest (one-time per Chrome profile):

   tap bridge setup

   This writes the Chrome native-messaging manifest that authorises this extension to launch the tap binary. No network ports are opened. No OS service is installed.

4. Click the Tap toolbar icon. The popup should say "Connected to local bridge". Done.

The bridge only runs while Chrome is open — closing every window shuts it down; re-opening Chrome (or clicking the toolbar icon) wakes it back up.

## Connect Your AI Agent (MCP)

Tap exposes 4 meta verbs (capture / verify / mark / run) as MCP tools and every saved plan as an MCP Resource.

**Claude Code / Cursor / Windsurf / Continue / Cline** — add to your MCP host config:

   {
     "mcpServers": {
       "tap": {
         "command": "tap",
         "args": ["mcp", "stdio"]
       }
     }
   }

Restart your host. You should see `capture`, `verify`, `mark`, `run` in the tool list and `tap://<site>/<name>` in resources. Ask your agent things like "use the tap MCP to run github/stars" or "capture this page with tap".

## Get the Most Out of Tap

   tap list                               # discover all saved plans
   tap list github                        # filter by substring
   tap show <site>/<name>                 # print the plan JSON
   tap run <site>/<name> k=v ...          # execute (zero LLM tokens)
   tap capture <url> <site>/<name> --intent "..."
                                          # author a new plan with AI
   tap verify <site>/<name>               # read-only health check

**Working patterns:**
- Let the agent author once, replay forever. Ask Claude/Cursor to "capture a tap for X" — the AI explores the page, you confirm with `tap mark <site>/<name> <key> committed`, and every subsequent run is deterministic and free.
- Pass arguments. Most community plans take args (`tap run reddit/post-comment subreddit=mcp body="..."`). Inspect with `tap show`.
- Compose plans. One plan can call another (`op:tap`) — build pipelines like "login → scrape → post" out of small reusable units.
- Schedule replays. Plans are JSON; run them from launchd / cron / GitHub Actions with no token cost.
- Convert existing Playwright / Puppeteer / Stagehand scripts — `npx @taprun/from-playwright <file>.spec.ts` emits a Tap plan you can run today.

Full guide & plan catalogue: https://taprun.dev
Spec & plan JSON Schema: https://taprun.dev/spec/plan-v1/
Source (MIT, includes this extension): https://github.com/LeonTing1010/tap

## Use Cases

- Authenticated scraping — pull data from any site you are logged into (dev tools, productivity apps, financial dashboards, internal portals) using your existing session, with zero cloud round-trip.
- Multi-step workflows — chain page-A → API-B → page-C with stable JSON plans that survive site refactors better than vision-based loops.
- AI-agent browser tools — give Claude Code, Cursor, or any MCP agent a browser without paying per-step token cost or shipping credentials anywhere.
- Personal automation — daily KB scans, dashboard checks, monitoring runs scheduled via launchd / cron, hitting authenticated sites that public scrapers can't touch.
- Migrating off cloud browser-automation — Stagehand / Browserbase / Apify users moving to a local-first model without rewriting their plan corpus (community plan-converters available for Playwright / Puppeteer / Stagehand sources).

## Troubleshooting

**Popup shows "Not connected to local bridge"**
The Tap CLI either isn't installed or the native-messaging manifest isn't registered. Run `tap --version` to confirm install, then `tap bridge setup` to register. Restart Chrome.

**`tap bridge setup` says "extension not found"**
The extension must be installed in the same Chrome profile you're configuring. If you use multiple profiles, switch to the one you want Tap on, then re-run `tap bridge setup`.

**`tap run <site>/<name>` returns `tap_not_found` but the file exists**
A different plan in `~/.tap/plans/` is malformed JSON and breaks enumeration. Validate with: `python3 -c "import json,glob; [json.load(open(p)) for p in glob.glob('$HOME/.tap/plans/**/*.plan.json', recursive=True)]"` — fix the bad file.

**`mcp__tap__capture` says "peer not registered"**
Chrome isn't open, or the extension is disabled, or this profile hasn't run `tap bridge setup`. Open Chrome, enable the extension, re-run setup.

**`runtime_unavailable` from MCP**
Let your MCP host launch `tap mcp stdio` for you (see the snippet above) — that path runs in-process and doesn't need a separate bridge. If you're using `tap mcp http`, confirm the daemon is running.

**Site needs a login I haven't done yet**
Just log in normally in Chrome first. Tap reuses your existing cookies — there's no separate Tap login.

**Site needs a secret/API key (not a cookie)**
Store it with `tap secret <KEY>` (reads value from stdin). Plans reference secrets by name; values never appear in plan JSON.

## FAQ

**Does Tap send my data anywhere?**
No. There is no Tap cloud, no telemetry, no license check. The extension only talks to the `tap` binary on your machine via Chrome Native Messaging. Network traffic from a plan goes to the site that plan targets — same destinations your browser already reaches.

**Do I need an API key to use Tap?**
No. The engine ships with no model and no key. Intelligence comes from the AI agent you connect via MCP — that's where your existing Anthropic / OpenAI / local-LLM token budget gets used, only at capture time.

**How is this different from Stagehand / Browserbase / browser-use?**
Those run in cloud browsers and need your credentials uploaded. Tap runs in your real Chrome. Same authenticated session you already have open; cookies and 2FA state never cross a trust boundary.

**How is this different from Playwright MCP / BrowserMCP?**
Those use vision or accessibility-tree loops that re-invoke the LLM on every step. Tap compiles a plan once, then replays as deterministic JSON dispatch — zero tokens, predictable timing, diff-able output.

**Can I share plans with my team?**
Yes. Plans are bare JSON files at `~/.tap/plans/<site>/<name>.plan.json`. Commit them to a git repo, share over Slack, or publish to the community catalogue at https://taprun.dev/taps/.

**Does Tap work on Firefox / Safari?**
Not yet. Chrome / Edge / Brave / Arc (any Chromium browser that supports Chrome Native Messaging and unpacked-extension installs) are supported.

**Will the bridge run in the background forever?**
No. The bridge only lives while Chrome is open. Closing the last Chrome window shuts it down. No daemon, no system service.

## Privacy & Security

- Everything stays on your machine. No data is sent to any Tap server (we don't operate one).
- The extension only reads tab content for tabs you have explicitly selected for automation. No background scraping.
- Cookies are read only for sites you have invoked an automation against, and are passed only to the local Tap binary over Chrome Native Messaging.
- No telemetry, no analytics, no license heartbeat. The MIT-licensed extension source is at https://github.com/LeonTing1010/tap/tree/main/extension.

See https://taprun.dev/privacy for the full policy.
