Chrome Toolbox MCP

中文说明

Let your AI assistant organize your Chrome reading list, tabs, tab groups and bookmarks, or search history. One Chrome extension, one local MCP server, and a checkbox for each capability.

Works with MCP clients including Claude Desktop, Claude Code, Cursor, Codex, opencode and Kilo. Only reading list access is enabled by default.

Setup

Requires Chrome 120+ and Node.js 18+.

1. Download and unzip extension.zip from the latest release, or use the repository's extension directory.

2. Open chrome://extensions, enable Developer mode, choose Load unpacked, and select extension.

3. Install the local server once:

   npm install -g github:ZhenningLang/chrome-toolbox-mcp

   Run the same command again to upgrade. Each assistant session starts its own server process, so a direct command keeps that small: launching through npx -y github:… adds an npm exec process per session (about 54 MB on macOS, versus about 41 MB for the server) and resolves GitHub on every start. npx still works if you only want to try it.

4. Add the local server to your MCP client, then restart the client.

Claude Code

claude mcp add -s user chrome-toolbox -- chrome-toolbox-mcp

Claude Desktop / Cursor: add this to your MCP configuration:

{
  "mcpServers": {
    "chrome-toolbox": { "command": "chrome-toolbox-mcp" }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.chrome-toolbox]
command = "chrome-toolbox-mcp"

opencode (~/.config/opencode/opencode.json) / Kilo (~/.config/kilo/kilo.json):

{
  "mcp": {
    "chrome-toolbox": {
      "type": "local",
      "command": ["chrome-toolbox-mcp"],
      "enabled": true
    }
  }
}

Check the connection and current capabilities:

chrome-toolbox-mcp doctor

doctor reports the configuration directory, local port, enabled capabilities and reading-list connection check. When reading-list access is off, that check is explicitly skipped rather than accessing a disabled capability.

Related MCP server: mcp-bookmark-server

Capability Switches

Click the Chrome Toolbox toolbar icon. The popup shows connection status, four checkboxes, descriptions and permission status.

Declining Chrome's permission prompt leaves the capability off. Unchecking an optional capability also returns its permissions. Changes persist locally; startup reconciles saved switches with permissions still granted by Chrome. The server lists only enabled tools, and the extension independently rejects disabled or revoked capabilities.

Some MCP clients may not refresh tools during a session. Start a new session after enabling a capability if its tools do not appear. Disabling access still takes effect immediately in the extension. If a lazy MCP wrapper uses --static-catalogue, remove that option from its configuration to allow dynamic tool-list notifications; this project does not edit client configuration automatically.

Tools

The six reading-list tool schemas and response shapes are unchanged. List supports status/search/pagination; add skips existing URLs; remove backs up the whole list first; restore re-adds missing entries; export supports Markdown, JSON and CSV.

tabs_open opens 1-100 URLs in the background by default. Use group: {"title":"Writing","collapsed":true} to create a named, collapsed group. tabs_move accepts 1-500 tab IDs and exactly one destination: groupId, newGroup, or ungroup:true. Group colors: grey, blue, red, yellow, green, pink, purple, cyan, orange. Group titles are limited to 80 characters.

tabs_close accepts 1-500 tab IDs and saves titles, URLs and group metadata in ~/.chrome-toolbox-mcp/backups/tabs-*.json before closing anything. A failed backup closes nothing. Reopen using tabs_open with backupPath; optional urls filters entries in that backup. Named groups are recreated, but a backup is not a full browser-session snapshot: form state, navigation stacks and original tab IDs are not restored.

Pending navigation targets are preserved. If any selected tab has no restorable URL, the whole close request is rejected and all selected tabs remain open. Existing group titles are restored without applying the 80-character limit for new group inputs. Opening/restoring a batch is not transactional if Chrome rejects an individual URL: already-created tabs remain.

bookmarks_search includes parent folder paths and defaults to 50 results (maximum 500). Add/move accepts exactly one of parentId or parentPath; missing path folders are created progressively. Omitting url when adding creates a folder. There is no bookmark deletion tool.

The first parentPath segment must name an existing root folder in Chrome's UI language (for example, Bookmarks bar in English). Alternatively, use a parentId returned by search.

history_search accepts ISO 8601 date-times with Z or a UTC offset (such as +08:00), or epoch-millisecond start/end times. Plain dates and local date-times without a timezone are rejected. Start defaults to 24 hours ago, text to all entries, and maxResults to 100 (maximum 1000). History tools are read-only.

Safety

• Browser-to-server traffic stays on 127.0.0.1:17893. The server accepts the fixed extension Origin; websites cannot use the bridge. Additional local clients authenticate with an owner-only token.

• Your AI client receives the data you enable, so its own provider/data policies still apply. Local transport does not mean an AI client cannot send results to its model provider.

• Reading-list removal and tab closure write owner-only backups before destructive calls. Backups may contain private titles and URLs.

• Multiple MCP processes share one extension through a hub; capability changes propagate to peers, including after reconnection and hub takeover.

• No page-content reading, clicking, screenshots, bookmark deletion, history deletion or saved-tab-group management.

Migration From The Old Name

The package was previously chrome-reading-list-mcp, and the extension was Reading List MCP. Update the unpacked extension in place and install the new package (npm install -g github:ZhenningLang/chrome-toolbox-mcp) and change client commands to chrome-toolbox-mcp. The fixed extension ID and port are unchanged; reading-list calls work with mixed old/new versions.

When the new default directory does not exist, the server renames ~/.chrome-reading-list-mcp to ~/.chrome-toolbox-mcp, preserving the token, backups and exports. Explicit HOME overrides are not migrated. If both directories already exist, neither is merged or overwritten.

Use CHROME_TOOLBOX_MCP_HOME, CHROME_TOOLBOX_MCP_PORT and CHROME_TOOLBOX_MCP_EXTENSION_IDS for new configuration. Legacy READING_LIST_MCP_* variables remain supported, with new variables taking priority. The frozen reading-list export schema retains its historical default-path description for compatibility; actual default exports use the new directory.

The GitHub repository is now ZhenningLang/chrome-toolbox-mcp. The old address still redirects, but install from the new one. The server never edits your client configuration.

Troubleshooting

• Extension not connected: keep Chrome open and the unpacked extension enabled. The ... badge means it is waiting for the MCP server. The AI client starts the server.

• Tool missing: check the popup, grant the requested permissions, and start a new assistant session if needed.

• chrome-toolbox-mcp not found: the client's PATH may not include npm's global bin directory (common for desktop apps on macOS). Use the absolute paths instead: "command": "<which node>" with "args": ["<npm root -g>/chrome-toolbox-mcp/src/cli.js"], filling in the output of which node and npm root -g.

• Port conflict: the extension uses 17893. Server PORT overrides are for diagnostics; changing the server alone does not change the extension's port.

Development

npm install
npm test                  # unit and fake-extension protocol tests
npm run test:e2e          # real Chrome for Testing, throwaway profile

Real Chrome smoke tests use the default port. Stop other copies before running them; set CHROME_BIN if Chrome for Testing is installed elsewhere. Optional permission dialogs and real-profile data require manual acceptance testing.

License

MIT