@thinkrun/mcp

MCP (Model Context Protocol) server for ThinkRun. Gives AI agents the ability to control your actual Chrome browser — with all your cookies and active sessions — or a cloud browser for headless automation.

Why ThinkRun vs Playwright MCP

TL;DR: Use ThinkRun when you need to browse as yourself (authenticated sites, internal tools). Use Playwright MCP for stateless public-web automation.

For the current checked-in parity contract and its supporting evidence, see:

• docs/mcp-cli-parity-matrix.md
• docs/mcp-cli-parity-evidence.md

Installation

First-run local setup

Use this path when you want the MCP server to control your real Chromium browser with your existing cookies and logged-in sessions:

npx @thinkrun/mcp doctor
npx @thinkrun/mcp install-native-host
npx @thinkrun/mcp doctor

Then open or reload Chrome with the ThinkRun extension enabled. doctor will tell you exactly what is missing: extension, native-host manifest, native-host binary, bridge port file, extension connection, or cloud API key.

install-native-host writes the ThinkRun native-host binary/config and browser native-messaging registration under your user profile. It delegates to a pinned compatible @thinkrun/cli installer so the download, checksum, and manifest behavior stay on the same path as the CLI.

On Windows, Chrome native messaging registration is stored in the registry. doctor reports that registry inspection as limited instead of treating the missing macOS/Linux manifest file as a setup failure.

Claude Code

claude mcp add thinkrun --transport stdio \
  -e THINKRUN_API_KEY=your-key \
  -- npx @thinkrun/mcp

Claude Desktop / Cursor / VS Code

Add to your MCP config file:

Auto mode (recommended) — tries local Chrome first, falls back to cloud:

{
  "mcpServers": {
    "thinkrun": {
      "command": "npx",
      "args": ["@thinkrun/mcp"],
      "env": {
        "THINKRUN_API_KEY": "your-key"
      }
    }
  }
}

Local only (Chrome extension, no API key needed):

{
  "mcpServers": {
    "thinkrun": {
      "command": "npx",
      "args": ["@thinkrun/mcp", "--mode", "local"]
    }
  }
}

Cloud only:

{
  "mcpServers": {
    "thinkrun": {
      "command": "npx",
      "args": ["@thinkrun/mcp", "--mode", "cloud"],
      "env": {
        "THINKRUN_API_KEY": "your-key"
      }
    }
  }
}

Security note: MCP config files (.cursor/mcp.json, .vscode/mcp.json) are often committed to git. Use environment variable references where supported, or add these files to .gitignore to avoid leaking your API key.

Global install (alternative)

npm install -g @thinkrun/mcp
thinkrun-mcp --mode auto

Modes

Page cache tools (page_cache_html, page_cache_text, page_cache_screenshot): stateless POST /api/cache/* on the service. In local mode, set THINKRUN_BASE_URL and THINKRUN_API_KEY (or pass --base-url / --api-key so the native host client can reach the API — the native host itself has no /api/cache routes).

Runtime switching: Use the set_mode tool to switch between local and cloud without restarting.

Local mode setup

MCP Server  ──HTTP──>  Native Host  ──stdio──>  Chrome Extension  ──>  Chrome tabs

1. Install the ThinkRun Chrome extension
2. Diagnose setup: npx @thinkrun/mcp doctor
3. Install/register the native host: npx @thinkrun/mcp install-native-host
4. Open or reload Chrome with the extension enabled
5. Verify: npx @thinkrun/mcp doctor
6. Add MCP config above

For unpacked/dev extensions, pass the browser extension ID explicitly:

npx @thinkrun/mcp install-native-host --extension-id <id>

Available Tools (53 + 1 optional)

53 tools are always registered. set_mode is registered when the server is started with mode-switch support (the default CLI binary enables it).

Session Lifecycle

Mode Switching

Stateless Page Cache

Navigation

Interaction

Observation

Tab Management

Dialog Handling

Wait

Monitoring

Local Actions

Local Diagnostics And Recovery

Task Planning

Hosted Remote Browser Control

ThinkRun also supports a hosted remote-agent flow for agents that are not running on the same machine as the browser.

This flow does not create a second browser-control surface. Hosted MCP remote browser access still goes through the same ThinkRun backend session APIs and ext-* relay path used by the existing browser control layer.

Remote-agent control tools

V1 rules

• remote agents authenticate as themselves with remote-agent credentials, not with the user's ThinkRun API key
• the user must already know and link the agent before browser access can be granted
• approval requires a logged-in ThinkRun session plus a live extension-connected browser session
• mutating scopes still require extension confirmation before use
• every remote command is authorized against live backend grant state
• evaluate remains denied for remote agents in v1 even if requested

Hermes / OpenClaw notes

For Hermes/OpenClaw-style agents running remotely:

1. register the agent and link it to the user account
2. call browser_request_control
3. wait for app approval and extension confirmation
4. use normal browser tools once the grant is active
5. release with browser_release_control

V1 usefulness is intentionally biased toward non-evaluate flows: snapshot, screenshot, click, fill, waits, tab tools, and artifact tools.

Remote workflows without evaluate

Remote-agent workflows in v1 should assume evaluate is unavailable even if a requested scope mentions it.

Recommended pattern:

1. browser_request_control
2. browser_grant_status
3. snapshot to inspect page structure
4. extract for text, HTML, or attributes
5. click / fill / type_text
6. wait_for_element or wait_for_text
7. screenshot for visual confirmation
8. browser_release_control

Good first-fit remote tasks in v1:

• inspect a dashboard and read current status
• click a refresh button and wait for updated text
• fill and submit ordinary non-sensitive form fields
• switch tabs and capture screenshots or artifacts

Not part of the default v1 path:

• arbitrary script execution
• password-field automation
• auth or payment submission flows
• destructive account actions on sensitive surfaces

Claude.ai compatibility

Claude-compatible hosted MCP clients can use the same request/grant/release contract, but v1 does not block release on unverified Claude.ai-specific connector or transport requirements outside the current ThinkRun MCP protocol surface.

If a Claude.ai integration has connector-specific auth or transport constraints, treat that as an integration concern rather than a reason to widen the remote browser authorization model.

Safety summary

• no remote direct connection to the extension WebSocket
• no approval authority in email links
• no evaluate for remote agents in v1
• sensitive-domain and high-risk operation blocking
• audited request/grant/command lifecycle

See docs/remote-browser-sharing.md for the user/admin model, operator runbook, and release checklist.

Local Session Semantics

The new local lifecycle tools intentionally distinguish between ownership-changing operations and focus-only operations:

• tab_attach rebinding: attaches to an existing local Chrome tab and sets it as the default session for subsequent session-scoped tool calls.
• window_new rebinding: opens a fresh local window and sets the resulting tab as the default session.
• tab_switch focus-only: changes the active local browser tab, but does not steal or rewrite the current default session just because browser focus changed.
• focus focus-only: foregrounds the currently bound local tab/window without rebinding or switching the default session.
• session_release clearing: releases the current local session ownership and clears the default session when that bound local context is released.

Lock safety follows the same high-level contract as the CLI:

• contested live local locks fail explicitly
• same-owner rebinds can succeed idempotently
• stale locks may be replaced only when the existing owner is no longer live

This package also exposes structured local diagnostics and bounded recovery rather than full CLI admin commands:

• local_diagnostics is the MCP equivalent for continuity/bridge truth that CLI users get from doctor and session debug
• local_reset_connection is the MCP equivalent for the CLI’s bounded reset-connection recovery path
• install/bootstrap/config flows remain CLI-only

This package now exposes the CLI's local native-host execution flow as:

• local_action_run
• local_action_status
• local_action_cancel

The naming is intentional:

• action means a direct operation against a browser context
• task means a higher-level cloud multi-step planning/execution workflow

CLI Options

thinkrun-mcp [options]

Options:
  --mode <mode>        cloud, local, or auto (default: auto)
  --api-key <key>      API key for cloud mode (or set THINKRUN_API_KEY)
  --base-url <url>     Cloud API URL (default: https://api.thinkrun.ai)
  --port <port>        Override native host port
  --session-id <id>    Default session ID (enables session_use)
  -h, --help           Show help
  -v, --version        Show version

Environment Variables

Port Discovery

The native host writes its port to ~/.thinkbrowse/port on startup. This path stays stable until the native-host cutover moves it to ~/.thinkrun/port. The MCP server reads this automatically.

Priority: --port flag > THINKRUN_BRIDGE_PORT env > ~/.thinkbrowse/port > 3012

Testing

# Unit tests
bun test

# Smoke test — full session lifecycle against cloud
THINKRUN_API_KEY=your-key bun run scripts/smoke-mcp-parity.ts

# Manual local parity smoke — requires live native host + extension bridge
bun run smoke:local-parity

# Manual local parity soak — repeats the same local parity assertions
THINKRUN_MCP_SOAK_ITERATIONS=50 bun run soak:local-parity

# Smoke test — clear_logs only
bun run test:smoke

Programmatic Usage

Basic:

import { createServer, CloudClient } from '@thinkrun/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const client = new CloudClient({
  baseUrl: 'https://api.thinkrun.ai',
  apiKey: process.env.THINKRUN_API_KEY!,
});

const server = createServer(client);
await server.connect(new StdioServerTransport());

With runtime mode switching:

import { createServer, CloudClient } from '@thinkrun/mcp';
import type { ClientRef } from '@thinkrun/mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const client = new CloudClient({
  baseUrl: 'https://api.thinkrun.ai',
  apiKey: process.env.THINKRUN_API_KEY!,
});

const clientRef: ClientRef = { current: client };
const server = createServer(client, {
  clientRef,
  onSetMode: async (mode) => {
    // Return a new client for the requested mode
    return new CloudClient({ baseUrl: '...', apiKey: '...' });
  },
});

await server.connect(new StdioServerTransport());

License

MIT