Summary
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.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
31 tools
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 params
Run 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....
Parameters* required
argsobjectTap arguments
namestringTap name
sitestringSite name
noSandboxbooleanDisable Worker sandbox (use when tap has DataCloneError)default: false
tap_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 params
Capture 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...
Parameters* required
formatstringone of
jpeg · pngdefault: jpegqualityintegerdefault: 50
tap_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 params
Read 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.
Parameters* required
sitestringlimitintegerdefault: 50
tap_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 params
Run 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...
Parameters* required
autobooleanAuto-heal: collect diagnostics for broken taps (current code + page inspection). AI reads diagnostics → forge.verify → forge.save.default: false
namestringFilter by tap name (optional)
sitestringFilter by site name (optional — omit for all)
formatstringOutput formatone of
json · junit · tapdefault: jsontimeoutintegerTimeout per tap in msdefault: 30000
tap_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 params
Run 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...
Parameters* required
argsobjectTap arguments
namestringTap name
sitestringSite name
keyColstringColumn to use as row identity for diffing
previousRowsarrayPrevious rows to diff against (omit for first run)
tap_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 params
Analyze 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.
Parameters* required
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 params
Load 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.
Parameters* required
pathstringPath to .tap.js file (e.g. ~/.tap/forge/draft.tap.js)
forge_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 params
Test 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.
Parameters* required
urlstringexpressionstringOptional — override expression instead of reading from draft
descriptionstringShort summary of what this verifies (e.g. 'HN posts with rank, title, points')
forge_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 params
Save 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.
Parameters* required
codestringOptional — override code instead of reading from draft
namestringsitestringtap_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 params
Navigate 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.
Parameters* required
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 params
Click 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.
Parameters* required
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 params
Type 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...
Parameters* required
textstringselectorstringtap_evalEvaluate JavaScript in the browser. The universal escape hatch — use when other tap.* tools can't do what you need.1 params
Evaluate JavaScript in the browser. The universal escape hatch — use when other tap.* tools can't do what you need.
Parameters* required
expressionstringtap_findFind elements by visible text. Returns position, selector, and bounding box. Use before click/type to verify the target exists.2 params
Find elements by visible text. Returns position, selector, and bounding box. Use before click/type to verify the target exists.
Parameters* required
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 params
Wait for a specified number of milliseconds. Use instead of tap.eval with setTimeout. For waiting on elements, prefer tap.waitFor(selector) instead.
Parameters* required
msintegerMilliseconds to waitdefault: 1000
tap_pressKeyPress a key.2 params
Press a key.
Parameters* required
keystringmodifiersintegerdefault: 0
tap_uploadUpload files to a file input. After uploading, check inspect.toasts for errors (wrong format, size limit).2 params
Upload files to a file input. After uploading, check inspect.toasts for errors (wrong format, size limit).
Parameters* required
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 params
Get page DOM structure.
Parameters* required
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 params
Inspect a specific element.
Parameters* required
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 params
Dump captured network log. Pass bodies:true to include response bodies (JSON APIs). Waits up to 3s for pending body fetches.
Parameters* required
bodiesbooleanInclude response bodies for API callsdefault: false
url_filterstringFilter entries by URL substring
inspect_downloadDownload and parse a URL.1 params
Download and parse a URL.
Parameters* required
urlstringtab_listList open browser tabs.
List open browser tabs.
No parameter schema in public metadata yet.
intercept_onEnable request interception.1 params
Enable request interception.
Parameters* required
patternsarrayintercept_offDisable request interception.
Disable request interception.
No parameter schema in public metadata yet.
Taprun
Browser automation that runs in your Chrome, not someone else's cloud.
Homepage | Blog | 70+ Skills | 中文
Local-first browser automation. Compile once, run forever at zero LLM tokens.
Point Taprun at any site. Your AI agent inspects the page once and emits a deterministic .plan.json program. Replay it forever — same result every call, $0 in tokens. Cookies and login sessions stay in your real Chrome — by architecture, not policy. tap verify catches breakage before your data goes stale.
Works with Claude Code, Cursor, Cline, Windsurf, and any MCP host. 70+ pre-built taps, or forge your own from any URL.
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
How Taprun Compares
| 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, 11-op closed vocabulary, git diff | Black box / ephemeral | Fragile scripts |
| MCP native | Yes (authoring layer only — execution is zero tokens) | No | No |
Get Started
1. Install
Zero-install via npx (any machine with Node):
npx -y @taprun/cli --version
The first run downloads the matching platform binary (~30MB) and caches it. Subsequent calls are instant.
Permanent install via curl (macOS / Linux):
curl -fsSL https://taprun.dev/install.sh | sh
Or via Homebrew (macOS / Linux):
brew install LeonTing1010/tap/taprun
| Platform | Download |
|---|---|
| macOS (Apple Silicon) | tap-macos-arm64 |
| macOS (Intel) | tap-macos-x64 |
| Linux | tap-linux-x64 |
| Windows | tap-windows-x64.exe |
2. Connect to Your AI Agent
Works with Claude Code, Cursor, Windsurf, or any MCP-compatible agent — no extension needed:
{ "mcpServers": { "tap": { "command": "npx", "args": ["-y", "@taprun/cli", "mcp", "stdio"] } } }
Or run the server directly:
tap mcp stdio # default; pipe to your MCP host
tap mcp http # streamable-HTTP on 127.0.0.1:7891 (bearer auth)
3. Go
tap github/trending # GitHub trending repos
tap hackernews/hot # Hacker News front page
tap weibo/hot # 微博热搜
tap xiaohongshu/search --keyword "AI" # 小红书搜索
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.
Optional: Chrome Extension (for login-required sites)
Most taps work without login. For sites that need your session (Xiaohongshu, Zhihu, etc.), install the Chrome Extension from the Chrome Web Store.
Optional: Embed in your agent code (TypeScript / Python)
Skip MCP — call the tap binary from your own loop:
tap hackernews/top --args '{}' # JSON-on-stdout, exit 0 on success
tap verify hackernews/top # 4-arm verdict (equivalent / drifted / first_snapshot / unreachable)
tap capture <url> hackernews/top --intent "front-page top stories"
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.
Have an existing Playwright / Puppeteer / Stagehand script?
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 (11-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).
What Can You Do?
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
How It Works
┌─ Chrome extension (your real browser sessions)
You → AI → Taprun ──────┤
capture └─ Playwright (headless, server, CI/CD)
- You describe what you want (URL × natural-language intent)
- AI compiles it into a
.plan.jsonprogram — bare JSON, 11-op closed vocabulary, version-controlled - Taprun runs the program on either runtime — forever, at $0
Every successful compilation makes the next one faster. 70+ community taps mean your agent already knows the common patterns.
Community Skills
tap-skills — 70+ taps, open source.
| Category | Examples |
|---|---|
| Trending | GitHub, Hacker News, Reddit, Product Hunt, Bilibili, Zhihu, Weibo, Xiaohongshu |
| Search | arXiv, Reddit, X, Zhihu, Weibo, Xiaohongshu, Bilibili, Medium |
| Read | Zhihu threads, Bilibili videos, Xiaohongshu notes, WeRead books |
| Write | X posts, Xiaohongshu notes, Zhihu articles, Dev.to, LinkedIn |
| Monitor | Price tracking, stock data, competitor analysis |
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
Local-first by architecture
Taprun runs in your browser, not someone else's cloud. The Chrome extension reuses your live login sessions; cookies, auth tokens, and credentials never leave your machine. This is 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.
Contributing
The easiest way to contribute: forge a new tap. One .plan.json file is all it takes.
See CONTRIBUTING.md for details.
Roadmap
- 70+ community taps across 70+ sites
- 2 runtimes — Chrome extension + Playwright (headless / CI)
- Unix pipes —
tap A | tap B - Watch mode — monitor changes over time
- Verify —
tap verifysnapshot-equivalence check with a 4-arm drift verdict (equivalent / drifted / first_snapshot / unreachable) - Single-command MCP server —
tap mcp stdio(ortap mcp http) for any MCP host - Android runtime
- iOS runtime
- Concurrency control — deterministic coordination for M agents operating shared accounts in parallel
Support
- GitHub Discussions — Q&A, ideas, show & tell
- support@taprun.dev — licensing, private feedback, consulting
- Issues — bug reports
License
Chrome Extension & docs: MIT. Community skills: MIT.
Star History
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Categories
Registryactive
Package@taprun/cli
TransportSTDIO
UpdatedMay 26, 2026
