๐ช TabNab
Give your AI your cookies, without giving it your password
Local MCP server that bridges AI agents with authenticated browser sessions
๐ Quick Start โข ๐ฆ Installation โข ๐ ๏ธ Tools โข ๐ Docs
โจ What is TabNab?
TabNab bridges the gap between AI agents (Claude, Cursor, Windsurf) and your real browser sessions. Instead of asking you to share passwords or API keys, TabNab lets AI agents use your existing authenticated browser sessions to:
- ๐ Navigate websites with your logged-in credentials
- ๐ Extract clean content from complex web pages
- โก Automate form filling and button clicks
- ๐ธ Capture screenshots for visual verification
- ๐ Access sites behind authentication and Cloudflare
The magic: AI agents see what you see in Chrome, using your cookies and sessions, without ever knowing your passwords.
๐ฏ Key Features
๐ Authenticated Access
Connect to your real Chrome browser with all your cookies & sessions intact via Playwright (CDP). No password sharing required.
๐ Clean Extraction
Uses Readability.js + Turndown to convert messy HTML into pristine Markdown for AI consumption.
๐จ Expanded MCP Tools
Complete browser automation via MCP protocol: tabs, navigation, extraction, query, keyboard, screenshots, and confirmations.
๐ Quick Start
1๏ธโฃ Prerequisites
- Node.js 22+ (Download)
- pnpm package manager (
npm install -g pnpm) - Chrome/Chromium browser
2๏ธโฃ Start Chrome with Remote Debugging
Recommendation: Use a dedicated Chrome profile for TabNab automation to isolate cookies and session data.
./scripts/start-chrome.sh
# or manually (dedicated profile recommended):
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/Library/Application Support/TabNab-Chrome"
./scripts/start-chrome.sh
# or manually (dedicated profile recommended):
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.config/tabnab-chrome"
.\scripts\start-chrome.ps1
# or manually (dedicated profile recommended):
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%LOCALAPPDATA%\TabNabChrome"
3๏ธโฃ Install & Build TabNab
git clone https://github.com/clduab11/tabnab.git
cd tabnab
pnpm install
pnpm run build
TabNab uses Playwright to attach to your existing Chrome via CDP. No extra browser download is required.
4๏ธโฃ Test the Connection
pnpm run test:milestone1
โ You should see your active tab's URL and title!
๐ฆ Installation
As an MCP Server (Recommended)
Configure TabNab as an MCP server in your AI agent client.
File Location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Configuration:
{
"mcpServers": {
"tabnab": {
"command": "node",
"args": ["/absolute/path/to/tabnab/dist/mcp/index.js"],
"env": {
"CHROME_DEBUG_PORT": "9222",
"TABNAB_ALLOWED_DOMAINS": "example.com,app.example.com",
"TABNAB_CONFIRMATION_MODE": "confirm-on-sensitive",
"TABNAB_AUDIT_LOG_PATH": "/tmp/tabnab-audit.log"
}
}
}
}
Follow similar configuration patterns for other MCP-compatible clients. See mcp-config.example.json for reference.
As a Standalone Electron App
pnpm run dev
Launches TabNab as a menu bar application.
๐ ๏ธ Available Tools
TabNab provides a focused set of MCP tools for browser automation with policy enforcement:
Response Contract & Versioning
All tool responses follow a shared contract:
{
"ok": true,
"success": true,
"protocolVersion": 2,
"warnings": [],
"data": {}
}
Errors use the same envelope with ok: false, an error object, and success: false for backward compatibility.
Tab Targeting
Use list_tabs to obtain stable tabId values. Every page/action tool accepts an optional tabId. If omitted, TabNab chooses the active tab by preferring the focused tab (if detectable), falling back to the last focused tab, and then the first non-extension/non-devtools tab.
Confirmation Flow
When a policy decision requires confirmation, tools return:
{
"ok": false,
"success": false,
"protocolVersion": 2,
"warnings": [],
"error": { "code": "NEEDS_CONFIRMATION", "message": "..." },
"data": { "confirmationId": "...", "actionSummary": "..." }
}
Call confirm_action with the confirmationId, then retry the original action with confirmationId to proceed. Use deny_action to reject the pending action.
Returns the URL and title of the currently active browser tab.
Example Output:
{
"ok": true,
"data": {
"url": "https://github.com/clduab11/tabnab",
"title": "TabNab - GitHub"
},
"warnings": []
}
Navigate to a URL and extract clean Markdown content using Readability.js (or sanitized DOM).
Example Input:
{
"url": "https://example.com/article",
"extractionMode": "readability_markdown"
}
Example Output:
{
"ok": true,
"data": {
"url": "https://example.com/article",
"title": "Article Title",
"markdown": "# Article Title\n\nClean extracted content..."
},
"warnings": []
}
Click an element on the current page using a CSS selector.
Example Input:
{
"selector": "button.submit-btn"
}
Example Output:
{
"ok": true,
"data": {
"message": "Clicked element: button.submit-btn"
},
"warnings": []
}
Fill an input field with the specified value. Clears existing content first.
Example Input:
{
"selector": "input[name='email']",
"value": "[email protected]"
}
Example Output:
{
"ok": true,
"data": {
"message": "Filled input: input[name='email']"
},
"warnings": []
}
Take a screenshot of the current tab. Returns base64-encoded data if no path specified.
Example Input:
{
"fullPage": false,
"path": "/path/to/screenshot.png"
}
Example Output:
{
"ok": true,
"data": {
"path": "/path/to/screenshot.png",
"message": "Screenshot saved to: /path/to/screenshot.png"
},
"warnings": []
}
๐ก๏ธ Policy & Safety Defaults
TabNab enforces a domain allowlist and confirmation gates by default. Actions that are blocked return ok: false with reasonCodes.
Environment Variables:
TABNAB_ALLOWED_DOMAINS="example.com,app.example.com"(required for navigation/click/fill)TABNAB_ALLOWED_PATH_PREFIXES="example.com:/billing;example.com:/settings"TABNAB_CONFIRMATION_MODE="auto|confirm-on-navigation|confirm-on-sensitive|always-confirm"TABNAB_AUDIT_LOG_PATH="/tmp/tabnab-audit.log"TABNAB_AUDIT_LOG_SELECTOR_MODE="truncate|hash|plaintext"TABNAB_MAX_STEPS="30"
Confirmation Flow:
- A tool may return
status: "needs_confirmation"with aconfirmation_token. - Call
confirm_actionto proceed or cancel.
Prompt-Injection Warnings: Extraction tools scan extracted content for instruction-like phrases and return warnings when detected.
๐๏ธ Architecture
graph TB
A[AI Agent<br/>Claude/Cursor/Windsurf] -->|MCP Protocol| B[TabNab MCP Server]
B -->|Chrome DevTools Protocol| C[Chrome Browser<br/>Port 9222]
C -->|Authenticated Sessions| D[Web Pages<br/>With Your Cookies]
style A fill:#e1f5ff,stroke:#01579b,stroke-width:2px
style B fill:#fff9c4,stroke:#f57f17,stroke-width:2px
style C fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
style D fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
Architecture Overview:
/src
/main - Electron menu bar application entry point
/mcp - MCP server implementation (stdio transport)
/browser - Chrome DevTools Protocol connection manager (Playwright CDP)
/extraction - HTML to Markdown conversion (Readability + Turndown)
๐ก Use Cases
๐ค AI-Powered Web Automation
Let Claude or Cursor automate tedious browser tasks using your existing sessions:
- Fill out forms on authenticated sites
- Navigate multi-step workflows
- Extract data from pages behind login
๐ Authenticated Data Collection
Gather information from sites where you're already logged in:
- Social media analytics
- Dashboard data extraction
- Research behind paywalls
๐งช Testing & QA
Automate browser testing with real authentication:
- Test logged-in user flows
- Verify form submissions
- Capture visual regressions
๐ Research & Analysis
Browse and analyze content with AI assistance:
- Summarize articles from subscription sites
- Extract structured data from complex pages
- Navigate and document web applications
๐ Documentation
- CLAUDE.md - Development guide for AI agents
- IMPLEMENTATION.md - Technical architecture details
- CONTRIBUTING.md - Contribution guidelines
- SECURITY.md - Security considerations & reporting
๐ค Contributing
We welcome contributions! See CONTRIBUTING.md for:
- Development environment setup
- Code style guidelines
- Pull request process
- Testing requirements
Before contributing, please review our:
- Code of Conduct (respect & professionalism)
- License Agreement (CLA terms)
๐ง Development
Prerequisites
- Node.js 22 LTS or higher
- pnpm 9.15.4+
- Chrome/Chromium with remote debugging
Commands
# Install dependencies
pnpm install
# Build project
pnpm run build
# Run type checking
pnpm run type-check
# Lint code
pnpm run lint
# Auto-fix linting issues
pnpm run lint:fix
# Format code
pnpm run format
# Run Electron app
pnpm run dev
๐ป Technology Stack
๐ License
TabNab is available under a dual-license model:
๐ Personal & Non-Commercial Use
Free under the PolyForm Shield License 1.0.0
โ Allowed:
- Personal projects and learning
- Academic and educational use
- Non-profit organizations (501(c)(3) or equivalent)
- Open source projects (non-commercial)
- Evaluation and testing
๐ผ Commercial Use
Requires a commercial license for any profit-generating activity:
โ Requires License:
- SaaS products using TabNab
- Internal business automation
- Consulting services using TabNab
- Any commercial product or service
- Use by for-profit organizations
๐ View Commercial License Terms โ
โ Not Sure Which License You Need?
See our Commercial License FAQ for detailed examples and guidance.
Contact for Commercial Licensing:
- Email: [email protected] (placeholder)
- GitHub: Open an Issue
โ ๏ธ Security Considerations
TabNab provides AI agents with powerful access to your authenticated browser sessions. Please understand the implications:
- ๐ Local Only: Only connects to
localhostChrome instances - ๐ช Cookie Access: AI agents can read your cookies and session tokens
- โก Live Actions: AI agents perform actions on your actual browser
- ๐ Trust Required: Only use with AI agents you trust completely
Best Practices:
- Use a dedicated Chrome profile for automation
- Monitor AI agent actions in real-time
- Don't use with highly sensitive accounts
- Review SECURITY.md for detailed guidance
Report Security Issues: [email protected] (placeholder)
๐ Acknowledgments
Built with:
- Chrome DevTools Protocol for browser control
- Readability.js by Mozilla for content extraction
- Turndown for HTML to Markdown conversion
- Model Context Protocol by Anthropic
Made with โค๏ธ for the AI automation community
TabNab ยฉ 2025 TabNab Contributors