Skip to content

Instantly share code, notes, and snippets.

@swapp1990

swapp1990/playwright-mcp-setup-plan.md

Created February 15, 2026 01:29
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save swapp1990/42f23994a5c6f65c3668275969087ac9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save swapp1990/42f23994a5c6f65c3668275969087ac9 to your computer and use it in GitHub Desktop.
Download ZIP
Playwright MCP Setup Plan for Telegram→Claude Browser Automation
Raw
playwright-mcp-setup-plan.md

Playwright MCP Setup for Telegram→Claude Browser Automation

1. Problem Statement

Claude in Chrome has persistent auth/connection issues and isn't designed for automated tasks triggered via Telegram /run commands. We need reliable browser automation that Claude Code can use natively — both in interactive sessions (where Swap watches) and in autonomous /run tasks (headless, in tmux). Currently there's no way to do browser actions like checking App Store keyword rankings through the Telegram→MacBook→Claude pipeline.

2. Solution Overview

Install Microsoft's Playwright MCP as a global Claude Code tool. Configure it for two modes: headless (for /run tasks in tmux) and headed (for interactive sessions). Set up a persistent browser profile so logged-in sessions survive across runs. Validate with an end-to-end test that goes from a Telegram /run command all the way through to browser automation and result delivery back to Telegram.

3. Comparison Table

Approach Reliability Auth Required Works in tmux Logged-in Sessions Cost
Claude in Chrome (current) Low — auth issues Chrome extension No (needs display) Yes (real browser) Free
Playwright MCP (proposed) High — deterministic None Yes (headless) Yes (persistent profile) Free
browser-use + API key Medium — AI flaky LLM API key Yes Yes (profile) LLM cost per run
Dedicated ASO tool High Account signup N/A N/A $50-300/mo

4. User Flow

  1. Swap sends /run check keyword ranking for "meditation timer" on App Store in any Telegram thread
  2. reply_handler.js picks it up, creates task file, triggers runner on MacBook
  3. run_wrapper.sh starts Claude Code in tmux with --dangerously-skip-permissions
  4. Claude Code reads the task, recognizes it needs browser automation
  5. Claude uses Playwright MCP tools to open a headless browser, navigate to apps.apple.com, search the keyword
  6. Claude scrolls through results, finds the app position, extracts ranking data
  7. Claude writes the result to output file and sends completion ACK
  8. Result delivered to Telegram thread: "Your app ranks #14 for 'meditation timer'"

5. Scope

P0 — Must Have

  • Playwright MCP installed globally for all Claude Code sessions
  • Headless mode working for /run tasks (tmux, no display)
  • Persistent browser profile that retains cookies/sessions across runs
  • E2E test: Telegram /run → browser action → result in Telegram
  • Verification that --dangerously-skip-permissions mode works with Playwright MCP tools

P1 — Should Have

  • Headed mode configuration for interactive/discuss sessions
  • Documentation of available Playwright MCP tools for prompt templates
  • A reusable prompt snippet for tasks that need browser automation

v2+ — Out of Scope

  • Replacing Claude in Chrome entirely (keep it for interactive desktop use)
  • Building a full ASO dashboard or scheduled keyword tracking
  • App Store Connect form filling automation
  • Multi-browser support (Firefox, WebKit) — Chromium only for now

6. Risks & Mitigations

Risk Impact Mitigation
Playwright MCP may not work with piped stdin (cat prompt | claude) High — blocks all /run usage Test this specific flow first before anything else
Headless Chromium may get blocked by App Store anti-bot Medium — ranking checks fail Use realistic user-agent, add delays between actions
Persistent profile may not survive across tmux sessions Medium — need re-login each time Test profile persistence, document profile location
Chrome v136+ user-data-dir restriction breaks profile reuse Medium — can't use default profile Use custom profile directory (already documented workaround)
MCP tool names may conflict with Claude in Chrome tools Low — confusing tool selection Verify tool namespacing, disable Claude in Chrome for /run tasks if needed
Playwright install may fail or need system dependencies on macOS Low — blocks setup Pre-check: npx @playwright/mcp@latest --help before configuring

7. Success Criteria Checklist

Setup

  • Playwright MCP registered as global Claude Code MCP server
  • npx @playwright/mcp@latest runs without errors on MacBook
  • Claude Code recognizes Playwright MCP tools (visible in /mcp output)
  • Persistent browser profile directory created and configured

Headless Mode (for /run tasks)

  • Playwright MCP works when Claude Code is launched via cat prompt | claude --dangerously-skip-permissions
  • Browser runs headless in tmux without requiring a display
  • Navigation, clicking, typing, and data extraction all work headless
  • Browser profile persists cookies between separate Claude sessions

E2E Pipeline

  • /run command from Telegram triggers task on MacBook
  • Claude Code starts, writes RUNNING ACK (visible in Telegram)
  • Claude uses Playwright to open a browser and perform the task
  • Result delivered back to Telegram as output
  • Full round-trip completes in under 3 minutes

Robustness

  • Graceful failure if Playwright MCP server fails to start
  • Browser timeout doesn't hang the Claude session
  • Step notes reflect browser automation progress ("Opening App Store...", "Searching for keyword...")

8. End-to-End Test List

E2E-1: Smoke test — Playwright MCP tool availability Verify Claude Code can list and invoke Playwright MCP tools in a fresh session started via piped stdin.

E2E-2: Headless navigation and data extraction Claude navigates to a known public page (e.g., example.com), extracts the page title, and returns it. Validates basic headless browser works in tmux.

E2E-3: App Store keyword search Claude opens apps.apple.com, searches for a keyword, scrolls through results, and reports the position of a specified app. Validates the primary use case.

E2E-4: Full Telegram pipeline Send /run from Telegram with a browser task. Verify RUNNING ACK appears, Claude performs browser automation, and the result is delivered back to the Telegram thread.

E2E-5: Session persistence Run two separate Claude sessions that use the same persistent profile. First session logs into a site, second session verifies the login persists.

9. Manual Testing Checklist

Smoke (2 min)

  • Run npx @playwright/mcp@latest --help — outputs help text
  • Start Claude Code interactively, type "list your playwright tools" — tools appear
  • Ask Claude to navigate to example.com — browser opens (headed) or returns content (headless)

Feature (5 min)

  • Send /run search App Store for 'meditation timer' and report results from Telegram
  • Watch tmux session — Claude writes ACKs and uses Playwright tools
  • Result appears in Telegram within 3 minutes
  • Run the same task again — persistent profile reused (no re-login needed if any auth was required)

Regression (2 min)

  • Regular /run tasks (non-browser) still work as before
  • Claude in Chrome still works for interactive desktop sessions
  • --dangerously-skip-permissions mode doesn't break with MCP enabled
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment