# Agentic Tab Organizer MCP

Connect any MCP-compatible AI agent to live tabs in a Chromium-based browser. The agent can list tabs, read selected page content, preview an organization plan, and consolidate retained tabs into one deduplicated window.

The organizer does not contain an AI model and does not require an AI API key. Your MCP client uses its existing model authentication. Stdio and standalone HTTP connections use a local pairing token shown by the extension; this token never leaves your machine.

## Capabilities

- List tabs from every normal browser window with titles, URLs, groups, and tab state
- Extract bounded readable text from selected HTTP and HTTPS tabs
- Close tabs by exact domain or explicit tab IDs, with optional subdomain matching
- Deduplicate exact normalized URLs while preserving the preferred copy
- Preserve pinned tabs during organization and arbitrary closes unless explicitly allowed
- Preview and validate ordered categories before changing the browser
- Create one destination window with visible tab groups or one flat left-to-right tab strip
- Sort and verify retained tabs before closing duplicates
- Connect through standard MCP stdio or local Streamable HTTP

## Requirements

- Brave Browser, Google Chrome, or another compatible Chromium browser
- Node.js 20 or newer
- An MCP-compatible agent such as OpenCode, Claude Desktop, Cursor, or another MCP client

Development and real-browser verification are performed primarily with Brave. Chrome and related Chromium browsers use the same extension APIs and are expected to work, but do not currently receive the same end-to-end coverage.

## Build

```bash
npx pnpm@11.24.0 install
npx pnpm@11.24.0 run build
```

Open `brave://extensions` in Brave or `chrome://extensions` in Chrome, enable **Developer mode**, select **Load unpacked**, and choose this repository's `dist` directory.

Open the extension popup and copy its **Local pairing token**.

## Connect An Agent

### Stdio

Stdio is the simplest option. Configure your MCP client with the absolute path to `dist-node/mcp-stdio.cjs`:

```json
{
  "mcpServers": {
    "agentic-tabs": {
      "command": "/absolute/path/to/agentic-tab-organizer/dist-node/mcp-stdio.cjs",
      "env": {
        "AGENTIC_TABS_BRIDGE_TOKEN": "TOKEN_FROM_EXTENSION_POPUP"
      }
    }
  }
}
```

The agent process opens a localhost-only browser bridge. The extension reconnects automatically.

### Streamable HTTP

Start the persistent local server:

```bash
AGENTIC_TABS_BRIDGE_TOKEN="TOKEN_FROM_EXTENSION_POPUP" npx pnpm@11.24.0 run mcp:http
```

Configure the MCP client to use:

```text
http://127.0.0.1:32145/mcp
```

Do not run stdio and HTTP modes simultaneously because both use the same local browser bridge port.

### Native Messaging

Native messaging is optional on macOS and Linux. The installer registers the same host for Google Chrome, Brave, and Chromium:

```bash
npx pnpm@11.24.0 run install:host
```

After reloading the extension, the browser launches the local HTTP MCP host automatically. Connect an HTTP MCP client to `http://127.0.0.1:32145/mcp`.

## Agent Workflow

The MCP exposes five tools:

| Tool | Purpose |
|---|---|
| `browser_list_tabs` | Read live tab and window metadata |
| `browser_get_tab_content` | Read bounded text from one tab for summarization or classification |
| `browser_close_tabs` | Close tabs by exact domain or explicit IDs after URL revalidation |
| `browser_plan_organization` | Validate ordered categories, choose duplicate keepers, and choose grouped or flat layout |
| `browser_apply_organization` | Apply an unexpired plan and return a verification report |

Example request:

> Inspect all browser tabs. Summarize ambiguous pages as needed, group them into Work, Reading, Social, Development, and Other, then preview the plan. After approval, consolidate them into one deduplicated window.

> Close all open tabs from amazon.nl.

`browser_plan_organization` accepts `createGroups`, which defaults to `true`. Set it to `false` to use the category order only for left-to-right placement: pinned tabs remain first, followed by each category in the order supplied, with no visible tab groups in the destination window.

> Consolidate all windows into one deduplicated window. Do not create tab groups; arrange the categories left-to-right instead.

## Safety And Privacy

- Planning does not modify the browser.
- Apply aborts when tabs, URLs, windows, pin state, order, or groups changed after planning.
- Duplicate tabs are closed only after retained tabs are verified in the destination window.
- `browser_close_tabs` supports an exact domain such as `amazon.nl` or explicit IDs returned by `browser_list_tabs`; leading `www` is normalized and subdomains require explicit opt-in.
- Before closing anything, the extension verifies that every selected tab still has the URL observed by the MCP server. If a tab navigated meanwhile, the entire close operation aborts.
- Pinned tabs are skipped by default and appear in `skippedTabs`; closing them requires `allowPinned: true`.
- Organization and arbitrary close operations share one mutation lock, preventing them from changing the browser concurrently.
- Incognito access is disabled.
- The local WebSocket bridge binds only to `127.0.0.1` and accepts the extension's fixed origin.
- The extension and local MCP process mutually authenticate with challenge-response HMAC; the pairing token is never transmitted.
- Page content is returned only when an agent calls `browser_get_tab_content`.
- Protected browser pages such as `brave://` and `chrome://` cannot be read, but they can still be listed and moved.
- Content returned to an agent may be sent to that agent's configured model provider.

## Development

```bash
npx pnpm@11.24.0 run typecheck
npx pnpm@11.24.0 run test:unit
npx pnpm@11.24.0 run test:integration
npx pnpm@11.24.0 run test:e2e
npx pnpm@11.24.0 run build
```

The end-to-end suite launches Brave with a disposable profile and never touches the user's normal browser profile. Brave is the primary verified browser; Chrome compatibility follows from the shared Chromium extension APIs and browser-neutral integration paths.