Think of this as a compiler for web tasks. Point Claude at any site once and Taprun emits a deterministic JSON plan that replays forever without burning tokens on subsequent runs. It uses your real Chrome profile, so cookies and login sessions stay local. The MCP server exposes capture, run, and verify operations. The verify command catches site changes before your data goes stale by checking a snapshot equivalence predicate. Ships with 70+ pre-built taps for GitHub trending, Hacker News, Weibo, Xiaohongshu. You can also convert existing Playwright or Puppeteer scripts into zero-token plans using the bundled adapters. Install via npx or direct binary, works with any MCP host.
Public tool metadata for what this MCP can expose to an agent.
tap_listList all available taps. ALWAYS call this first before any tap.* tool. If a matching tap exists, use tap.run — it executes with zero AI, faster and more stable than manual tap operations. NEVER bypass a tap by using manual tap.* calls to replicate what a tap already does.List all available taps. ALWAYS call this first before any tap.* tool. If a matching tap exists, use tap.run — it executes with zero AI, faster and more stable than manual tap operations. NEVER bypass a tap by using manual tap.* calls to replicate what a tap already does.
No parameter schema in public metadata yet.
tap_runRun a pre-built tap. Preferred over tap.* tools — deterministic, zero AI at runtime. Returns {columns, rows, count, timing}. If rows is empty or error, use tap.doctor(site, name) for structured diagnosis before re-forging. On transient failure (timeout, connection), RETRY tap....4 paramsRun a pre-built tap. Preferred over tap.* tools — deterministic, zero AI at runtime. Returns {columns, rows, count, timing}. If rows is empty or error, use tap.doctor(site, name) for structured diagnosis before re-forging. On transient failure (timeout, connection), RETRY tap....
argsobjectnamestringsitestringnoSandboxbooleantap_screenshotCapture the current page as an image. LAST RESORT — before using this, prefer: (1) inspect.toasts for operation feedback, (2) tap.eval to check DOM state/URL, (3) inspect.page for url+title. Only use screenshot for visual verification (layout, rendering). When you do use it, p...2 paramsCapture the current page as an image. LAST RESORT — before using this, prefer: (1) inspect.toasts for operation feedback, (2) tap.eval to check DOM state/URL, (3) inspect.page for url+title. Only use screenshot for visual verification (layout, rendering). When you do use it, p...
formatstringjpeg · pngdefault: jpegqualityintegertap_logsRead tap execution history (run + forge events). Filter by site to narrow results. Use to diagnose failures: check error fields, row counts, timing. Consistently 0 rows or repeated errors → use forge.inspect to re-forge.2 paramsRead tap execution history (run + forge events). Filter by site to narrow results. Use to diagnose failures: check error fields, row counts, timing. Consistently 0 rows or repeated errors → use forge.inspect to re-forge.
sitestringlimitintegertap_doctorRun health checks on taps. Returns {status, score, rows, issues[], error} per tap. Use as: (1) diagnostic entry point when tap.run fails — doctor gives structured root cause, (2) post-save validation after forge.save — doctor confirms health contract passes, (3) batch health a...5 paramsRun health checks on taps. Returns {status, score, rows, issues[], error} per tap. Use as: (1) diagnostic entry point when tap.run fails — doctor gives structured root cause, (2) post-save validation after forge.save — doctor confirms health contract passes, (3) batch health a...
autobooleannamestringsitestringformatstringjson · junit · tapdefault: jsontimeoutintegertap_watchRun a tap once and diff against previous rows. Returns {rows, events[], hasChanges}. Events: added/removed/changed with row data. Stateless — first call: omit previousRows to get baseline. Subsequent calls: pass previous rows to detect changes. Use for monitoring (price change...5 paramsRun a tap once and diff against previous rows. Returns {rows, events[], hasChanges}. Events: added/removed/changed with row data. Stateless — first call: omit previousRows to get baseline. Subsequent calls: pass previous rows to detect changes. Use for monitoring (price change...
argsobjectnamestringsitestringkeyColstringpreviousRowsarraytap_reloadPush updated taps to all connected runtimes (extension, Playwright) without restarting the daemon. Normally not needed — forge.save auto-notifies. Use after manual tap file edits or tap update.Push updated taps to all connected runtimes (extension, Playwright) without restarting the daemon. Normally not needed — forge.save auto-notifies. Use after manual tap file edits or tap update.
No parameter schema in public metadata yet.
tap_versionGet protocol version and connected runtime info. Use to verify the extension is connected and check version compatibility before running taps.Get protocol version and connected runtime info. Use to verify the extension is connected and check version compatibility before running taps.
No parameter schema in public metadata yet.
forge_inspectAnalyze a page for tap forging: detects framework, SSR state, APIs, and generates extraction strategies. Also use this to re-forge a broken tap — inspect the page again to find what changed.1 paramsAnalyze a page for tap forging: detects framework, SSR state, APIs, and generates extraction strategies. Also use this to re-forge a broken tap — inspect the page again to find what changed.
urlstringforge_draftLoad a .tap.js file into memory for verification. Write the tap code to a file first, then pass the path here. Returns content hash for change tracking.1 paramsLoad a .tap.js file into memory for verification. Write the tap code to a file first, then pass the path here. Returns content hash for change tracking.
pathstringforge_verifyTest the draft tap's extraction logic live on a URL. Reads code from forge.draft — no need to pass expression. Returns score, rows, and data preview.3 paramsTest the draft tap's extraction logic live on a URL. Reads code from forge.draft — no need to pass expression. Returns score, rows, and data preview.
urlstringexpressionstringdescriptionstringforge_saveSave the draft tap to disk and auto-commit to git. Reads code from forge.draft — no need to pass code. After saving, tap.run can execute it forever with zero AI.3 paramsSave the draft tap to disk and auto-commit to git. Reads code from forge.draft — no need to pass code. After saving, tap.run can execute it forever with zero AI.
codestringnamestringsitestringtap_navNavigate to a URL. Before calling this, check tap.list — if a tap exists for this site/task, use tap.run instead. Returns {url, title}. If url differs from requested, a redirect occurred.1 paramsNavigate to a URL. Before calling this, check tap.list — if a tap exists for this site/task, use tap.run instead. Returns {url, title}. If url differs from requested, a redirect occurred.
urlstringtap_clickClick on an element by visible text or CSS selector. Returns the resulting url and title. After clicking, check inspect.toasts for feedback (errors, confirmations) before proceeding. Use tap.find first if unsure whether the element exists.1 paramsClick on an element by visible text or CSS selector. Returns the resulting url and title. After clicking, check inspect.toasts for feedback (errors, confirmations) before proceeding. Use tap.find first if unsure whether the element exists.
targetstringtap_typeType text into an input. Auto-detects editor type (standard input, contentEditable, CodeMirror, Draft.js, ProseMirror). Returns the current value — if it doesn't match your input, try tap.eval with execCommand('insertText') or the editor's native API. After typing, check inspe...2 paramsType text into an input. Auto-detects editor type (standard input, contentEditable, CodeMirror, Draft.js, ProseMirror). Returns the current value — if it doesn't match your input, try tap.eval with execCommand('insertText') or the editor's native API. After typing, check inspe...
textstringselectorstringtap_evalEvaluate JavaScript in the browser. The universal escape hatch — use when other tap.* tools can't do what you need.1 paramsEvaluate JavaScript in the browser. The universal escape hatch — use when other tap.* tools can't do what you need.
expressionstringtap_findFind elements by visible text. Returns position, selector, and bounding box. Use before click/type to verify the target exists.2 paramsFind elements by visible text. Returns position, selector, and bounding box. Use before click/type to verify the target exists.
rolestringquerystringtap_waitWait for a specified number of milliseconds. Use instead of tap.eval with setTimeout. For waiting on elements, prefer tap.waitFor(selector) instead.1 paramsWait for a specified number of milliseconds. Use instead of tap.eval with setTimeout. For waiting on elements, prefer tap.waitFor(selector) instead.
msintegertap_pressKeyPress a key.2 paramsPress a key.
keystringmodifiersintegertap_uploadUpload files to a file input. After uploading, check inspect.toasts for errors (wrong format, size limit).2 paramsUpload files to a file input. After uploading, check inspect.toasts for errors (wrong format, size limit).
filesstringselectorstringtap_cookiesGet cookies for the current site.Get cookies for the current site.
No parameter schema in public metadata yet.
inspect_domGet page DOM structure.1 paramsGet page DOM structure.
selectorstringinspect_pageGet page info (url, title, meta).Get page info (url, title, meta).
No parameter schema in public metadata yet.
inspect_a11yGet accessibility tree.Get accessibility tree.
No parameter schema in public metadata yet.
inspect_elementInspect a specific element.1 paramsInspect a specific element.
selectorstringinspect_networkStartStart network capture.Start network capture.
No parameter schema in public metadata yet.
inspect_networkDumpDump captured network log. Pass bodies:true to include response bodies (JSON APIs). Waits up to 3s for pending body fetches.2 paramsDump captured network log. Pass bodies:true to include response bodies (JSON APIs). Waits up to 3s for pending body fetches.
bodiesbooleanurl_filterstringinspect_downloadDownload and parse a URL.1 paramsDownload and parse a URL.
urlstringtab_listList open browser tabs.List open browser tabs.
No parameter schema in public metadata yet.
intercept_onEnable request interception.1 paramsEnable request interception.
patternsarrayintercept_offDisable request interception.Disable request interception.
No parameter schema in public metadata yet.
Homepage | Blog | Verified Claims | 中文
Your agent's closed-loop action layer for the browser — the login-gated, exception-heavy, compliance-critical last 20% that clean APIs and cloud agents can't reach. Driven in your own Chrome, captured once, replayed forever at zero LLM tokens.
As APIs get walled off and metered, the work that survives lives behind logins, OTP walls, and human-gesture gates — the exceptions, approvals, and compliance steps a cloud agent architecturally can't touch. Taprun is the action layer for exactly that: your agent drives your real, already-logged-in Chrome, closes the loop (act → verify the effect → re-run on drift), and hands you a deterministic replay you own.
Every other browser agent re-runs a live LLM — and re-burns tokens — on every execution. Taprun's AI agent inspects the page once and emits a deterministic .plan.json program; every replay after that is pure data dispatch — same result every call, $0 in tokens, no agent in the loop. It runs in your real Chrome, so cookies and login sessions stay on your machine by architecture. tap verify catches breakage before your data goes stale.
Works with Claude Code, CodeBuddy, Cursor, Cline, Windsurf, and any MCP host — install straight from the chat window. Forge a tap from any URL on demand — no catalog needed.
Capture: AI inspects the site → compiles a .plan.json program (one-time cost)
Run: The program executes instantly, same result every time ($0, zero AI)
Verify: tap verify checks the snapshot equivalence predicate (catches drift)
Repair: re-run capture against the same site/name; the next (only when needed)
verify rebaselines after human review
| Taprun | AI Browser Agents | Traditional Scrapers | |
|---|---|---|---|
| AI cost per run | $0 (compile once) | Tokens every run | Free |
| Accuracy | Deterministic | Varies per run | Deterministic |
| Silent failure detection | Per-tap CEL snapshot_equivalent predicate + 4-arm verdict | None | None |
| Breakage diagnostics | tap verify — exact diff of what changed | None | Manual spot checks |
| Detection risk | Low (real browser sessions) | High | High |
| Runtimes | 2 (Chrome extension + Playwright) | 1 | 1 |
| Code inspectable | .plan.json — bare JSON, 18-op closed vocabulary, git diff | Black box / ephemeral | Fragile scripts |
| MCP native | Yes (authoring layer only — execution is zero tokens) | No | No |
Claude Code / CodeBuddy — paste two lines into the chat, nothing else:
/plugin marketplace add LeonTing1010/taprun
/plugin install tap@taprun
That installs the Tap MCP server plus the skills that teach your agent when to use it and the hook that routes walled fetches to Tap — no terminal, no config file. (CodeBuddy wires plugin MCP servers at startup only, so fully restart it once after installing; Claude Code picks them up with /reload-plugins.)
Any other MCP host (Cursor · VS Code · Claude Desktop) — one command writes the config for you:
npx -y @taprun/cli embed cursor # or: vscode | claude-desktop | claude-code | codebuddy | qwen
The binary self-copies to ~/.tap/bin and your agent's MCP config is written. Re-check anytime with tap embed --verify.
Using a coding agent that isn't in that list?
tap embedtargets are data, not code: drop a row into~/.tap/embed-targets.jsonand the new agent works immediately — no engine release. Each row names one of four install kinds (cc-pluginfor Claude-Code-plugin hosts,cli-mcp-addfor CLIs with a<cli> mcp add,ide-deeplink,desktop-bundle), e.g.[{"id":"kode","kind":"cc-plugin","display":"Kode CLI","tier":1,"cli":"kode"}]. Same doctrine as the rest of Tap — the engine stays closed and mechanical; you extend it in local data.
Now pick your runtime — the extension is only needed to reuse your live logged-in Chrome:
npx; you're done. Append --no-extension for a fully in-chat Playwright runtime with its own isolated profile (no browser gesture, no click).npx already downloaded — no second download) and registers the native-messaging manifest, then opens the extension page. The single Add to Chrome click is the only step that isn't a chat action — it is the trust gate that lets Tap reuse your existing login, and the in-flight call resumes automatically once it lands.tap.mcpb and double-click.brew install LeonTing1010/tap/taprun # Homebrew (macOS / Linux)
curl -fsSL https://taprun.dev/install.sh | sh # permanent binary
npx -y @taprun/cli --version # zero-install (any Node host)
Manual MCP config, if you'd rather write it yourself:
{ "mcpServers": { "tap": { "command": "npx", "args": ["-y", "@taprun/cli", "mcp", "stdio"] } } }
| Platform | Download |
|---|---|
| macOS (Apple Silicon) | tap-macos-arm64 |
| macOS (Intel) | tap-macos-x64 |
| Linux | tap-linux-x64 |
| Windows | tap-windows-x64.exe |
Run the first entry of the claims ledger — the exact verification its nightly CI runs:
mkdir -p ~/.tap/plans/github
curl -fsSL https://raw.githubusercontent.com/LeonTing1010/tap-skills/main/claims/2026-07-11-github-trending-has-no-api/plan.json \
-o ~/.tap/plans/github/trending-no-api.plan.json
tap github/trending-no-api
"state": "committed" plus today's trending repos at zero tokens = your install works and the claim holds.
tap capture https://news.ycombinator.com hn/front --intent "front-page stories with points"
tap hn/front # replay forever, $0
Or just ask your AI agent:
You: What's trending on GitHub today?
Agent: Here are today's top repos — React compiler hit 734 stars...
You: Capture a tap for Douban top 250 movies
Agent: Done. Run `tap douban/top250` anytime — $0 per run.
Skip MCP — call the tap binary from your own loop:
tap capture <url> hackernews/top --intent "front-page top stories"
tap hackernews/top --args '{}' # JSON-on-stdout, exit 0 on success
tap verify hackernews/top # 3-arm verdict (live / drifted / unreachable)
The CLI emits ToolResult<T> envelopes as JSON — same shape the MCP surface returns — so any language with a subprocess library can drive it. See tap --help for the full verb list.
Don't rewrite. Convert with one of the open-source adapters — drop your existing source in, get a Tap-compatible .plan.json plan out:
# Existing Playwright script (47M weekly npm downloads — most likely the one you have)
npm install @taprun/from-playwright @taprun/spec
node -e "import('@taprun/from-playwright').then(m => console.log(m.playwrightToTap(require('fs').readFileSync('tests/login.spec.ts','utf8'), {site:'example', name:'login'})))"
# Or scaffold a new starter from scratch
npx create-tap-script github/trending https://github.com/trending
| Adapter | Source format | Coverage |
|---|---|---|
@taprun/from-playwright | .ts/.js Playwright tests | 8 page.* APIs (goto/click/fill/type/press/waitForSelector/waitForTimeout/screenshot) |
@taprun/from-puppeteer | .ts/.js Puppeteer scripts | 7 page.* APIs + page.keyboard.press |
@taprun/from-stagehand | .ts/.js Stagehand scripts | Hybrid: deterministic page.* mapped to plan ops; NL act/extract/observe flagged for honest verify verdicts |
create-tap-script | (none — scaffolder) | Generates a starter .plan.json envelope from <site>/<name> <url> |
The format itself is documented at @taprun/spec — the public protocol surface package: TypeScript types for the v2 Plan (18-op closed union + discriminated read/write Plan union) + JSON Schema 2020-12 with $id resolvable at taprun.dev/spec/plan-v1/schema.json, bidirectionally drift-guarded against the TS types. Third-party tooling (IDE $schema autocomplete, ajv-equivalent validators in Python/Ruby/Go, governance layers, alternative runtimes, MCP hosts with plan-aware permission scoping) builds against this package without depending on the proprietary Tap engine. Plan-v1 reference: taprun.dev/spec/plan-v1. Source for all five packages: packages/ (see packages/README.md for the workspace overview).
Read — Extract data from any website
tap reddit/hot # Reddit front page
tap bilibili/trending # Bilibili trending
tap arxiv/search --keyword "LLM" # arXiv papers
Write — Operate any website
tap xiaohongshu/publish --title "My Note" --images photo.jpg
tap zhihu/publish --title "My Article" --content "..."
Watch — Monitor changes
tap verify github/trending # spot drift; schedule via cron / launchd
Compose — Chain like Unix pipes
tap github/trending | tap filter --field stars --gt 500 | tap table
Forge — Create new automations with AI
tap capture https://news.ycombinator.com hackernews/hot --intent "top stories" # API detected — compiled without AI
tap capture https://example.com mysite/home --intent "..." # BYOK Claude / GPT for the long tail
Bring your own model — works with Claude, OpenAI, DeepSeek, or any OpenAI-compatible endpoint including local Ollama / LM Studio for fully offline forge:
tap config set ai.baseUrl http://localhost:11434/v1
tap config set ai.key ollama
tap config set ai.model llama3.1
tap capture https://arxiv.org/list/cs.AI/recent arxiv/recent --intent "recent papers" # 0 bytes leave your machine
┌─ Chrome extension (your real browser sessions)
You → AI → Taprun ──────┤
capture └─ Playwright (headless, server, CI/CD)
.plan.json program — bare JSON, 18-op closed vocabulary, version-controlledEvery successful compilation makes the next one faster. Need a tap for a new site? Your agent forges one on demand with capture — no catalog required.
tap-skills is no longer a skills catalog — it's a claims ledger: dated, falsifiable claims about the live web, each vendoring its own deterministic plan, re-verified nightly by CI at zero LLM tokens. A claim that drifts flips to 🟡 publicly, the same night.
Verify the first claim yourself (~2 minutes, no login, no browser):
mkdir -p ~/.tap/plans/github
curl -fsSL https://raw.githubusercontent.com/LeonTing1010/tap-skills/main/claims/2026-07-11-github-trending-has-no-api/plan.json \
-o ~/.tap/plans/github/trending-no-api.plan.json
npx -y @taprun/cli github/trending-no-api
You get the exact verification the nightly CI gets — deterministic replay, same result. The 140-skill v1 catalog is preserved untouched on the v1-archive branch; pre-built catalogs only rot, so plans are forged on demand with capture instead.
tap verify <site>/<name> # Snapshot equivalence — catches silent failures before your data goes stale
tap list # See everything available
tap show <site>/<name> # Print the saved tap's plan as JSON
Zero-token replay is the headline; local-first is the guarantee underneath it. Taprun runs in your browser — the Chrome extension reuses your live login sessions, so cookies, auth tokens, and credentials never leave your machine. A structural choice, not a marketing claim:
| Concern | Cloud-first browser SDKs | Taprun (local-first) |
|---|---|---|
| Where do logged-in cookies live? | On the cloud vendor's servers | Only in your local browser |
| What does the AI see? | The full session + your data | Only the page DOM during forge time |
Compliance with noindex / robots.txt / TOS | Vendor signs ToS for you | Your account, your terms |
| Internal / intranet sites | Need VPN tunneling | Just open the page |
| Decommission risk | Vendor goes down → your scrapers stop | Local code keeps running |
| Layer | Protection |
|---|---|
| Sandbox | Programs run with zero permissions — no file, network, or system access |
| Static Analysis | CI blocks dangerous patterns before they reach users |
| Local-only | Your data, sessions, and API keys never leave your machine — architecturally |
See SECURITY.md for the full threat model.
The easiest way to contribute: forge a new tap. One .plan.json file is all it takes.
See CONTRIBUTING.md for details.
tap A | tap Btap verify snapshot-equivalence check with a 4-arm drift verdict (equivalent / drifted / first_snapshot / unreachable)tap mcp stdio (or tap mcp http) for any MCP hostTap is local-first by architecture. It drives your own browser on your own machine — credentials, cookies, and page data never leave it. The engine ships no telemetry and makes no outbound network calls except the ones your own saved taps explicitly direct (op:fetch). Saved taps, secrets, and traces live under ~/.tap/ on your machine only.
Full policy: taprun.dev/privacy.
Chrome Extension & docs: MIT. Claims ledger: MIT.
therealtimex/browser-use
jae-jae/fetcher-mcp
merajmehrabi/puppeteer-mcp-server
com.thenextgennexus/playwright-mcp-server
saik0s/mcp-browser-use