ThinkBrowse MCP

Control browsers using ThinkBrowse MCP tools (mcp__thinkbrowse__*). 35 tools. Three modes: auto (default), local, cloud.

Every tool call MUST include a thought parameter explaining your reasoning.

Quick Start

1. session_create          → get a session
2. session_wait_ready      → wait for provisioning (cloud)
3. navigate                → go to URL
4. snapshot                → read page structure (best for AI)
5. screenshot              → visual capture
6. click / type_text       → interact
7. session_delete          → clean up

Top 5 Patterns

1. Navigate → Snapshot → Act

snapshot  {thought: "Read page structure before interacting"}
click  {selector: "button[type=submit]", thought: "Click submit — confirmed via snapshot"}

Always snapshot before clicking to find the right selector.

2. Click by Text (When Selectors Are Ambiguous)

evaluate  {
  script: "[...document.querySelectorAll('button,a,[role=button]')].find(el=>el.textContent.trim()==='Sign In')?.click()",
  thought: "Multiple buttons — clicking by visible text"
}

3. React Forms (type_text, NOT fill)

click  {selector: "input[name=email]", thought: "Focus email field"}
type_text  {selector: "input[name=email]", text: "user@example.com", thought: "React input — using type_text"}
click  {selector: "button[type=submit]", thought: "Submit form"}

fill uses native DOM value setting — React won't detect the change. type_text uses keyboard events.

4. List Interactive Elements

evaluate  {
  script: "[...document.querySelectorAll('button,[role=tab],a')].map(b=>({label:b.getAttribute('aria-label'),text:b.textContent.trim().slice(0,50),tag:b.tagName})).filter(b=>b.text||b.label)",
  thought: "Find all clickable elements"
}

5. Cloud Session Lifecycle

session_create  {thought: "Create cloud session"}
session_wait_ready  {sessionId: "...", thought: "Wait for provisioning (60-90s)"}
navigate  {url: "https://example.com", thought: "Go to target"}
...
session_delete  {sessionId: "...", thought: "Clean up"}

Always session_wait_ready after session_create in cloud mode. Always session_delete when done.

For all 10+ patterns, see references/patterns.md.

Top 5 Anti-Patterns

1. Clicking without observing first

# BAD — may click wrong element or get ELEMENT_NOT_FOUND
click  {selector: "button", thought: "Click the button"}

# GOOD — observe first
snapshot  {thought: "Find correct selector"}
click  {selector: "button[aria-label='Submit']", thought: "Click submit confirmed via snapshot"}

2. Using fill for React inputs

# BAD — React won't detect value change
fill  {selector: "#search", value: "query"}

# GOOD — keyboard events trigger React onChange
type_text  {selector: "#search", text: "query", thought: "React input"}

3. Skipping session_wait_ready in cloud mode

# BAD — session still provisioning, actions fail
session_create → navigate  # ERROR

# GOOD
session_create → session_wait_ready → navigate

4. Expecting evaluate to return async values

# BAD — returns null/empty
evaluate  {script: "fetch('/api/data').then(r => r.json())"}

# GOOD — use network_requests instead
network_requests  {thought: "Check API calls the page made"}

5. Missing thought parameter

# BAD — no audit trail
click  {selector: "#delete"}

# GOOD
click  {selector: "#delete", thought: "Delete draft post as requested"}

Essential Gotchas

Observation Strategy

Always prefer snapshot over screenshot for decision-making:

Recommended flow: snapshot → evaluate → screenshot

Mode Comparison

Local: auth-required sites, WebSockets, interactive dev, free. Cloud: headless scraping, anti-detection, multi-agent, no Chrome needed.

Config

Install: npx @thinkbrowse/mcp or npm install -g @thinkbrowse/mcp Environment: THINKBROWSE_API_KEY for cloud mode. Config: ~/.config/thinkbrowse/config.json — {"apiKey": "...", "apiUrl": "https://api.thinkbrowse.io"}

References

• For complete tool reference (all 35 tools), see references/tool-reference.md
• For all 10+ patterns and additional gotchas, see references/patterns.md
• For error codes and recovery playbooks, see references/error-recovery.md