browsing-with-playwright

Browser Automation

Automate browser interactions via Playwright MCP server.

Server Lifecycle

Start Server

# Using helper script (recommended)
bash scripts/start-server.sh
 
# Or manually
npx @playwright/mcp@latest --port 8808 --shared-browser-context &

Stop Server

# Using helper script (closes browser first)
bash scripts/stop-server.sh
 
# Or manually
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_close -p '{}'
pkill -f "@playwright/mcp"

When to Stop

End of task: Stop when browser work is complete
Long sessions: Keep running if doing multiple browser tasks
Errors: Stop and restart if browser becomes unresponsive

Important: The --shared-browser-context flag is required to maintain browser state across multiple mcp-client.py calls. Without it, each call gets a fresh browser context.

Quick Reference

# Go to URL
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate \
  -p '{"url": "https://example.com"}'
 
# Go back
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate_back -p '{}'

Get Page State

# Accessibility snapshot (returns element refs for clicking/typing)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'
 
# Screenshot
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_take_screenshot \
  -p '{"type": "png", "fullPage": true}'

Interact with Elements

Use ref from snapshot output to target elements:

# Click element
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click \
  -p '{"element": "Submit button", "ref": "e42"}'
 
# Type text
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_type \
  -p '{"element": "Search input", "ref": "e15", "text": "hello world", "submit": true}'
 
# Fill form (multiple fields)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_fill_form \
  -p '{"fields": [{"ref": "e10", "value": "john@example.com"}, {"ref": "e12", "value": "password123"}]}'
 
# Select dropdown
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_select_option \
  -p '{"element": "Country dropdown", "ref": "e20", "values": ["US"]}'

Wait for Conditions

# Wait for text to appear
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"text": "Success"}'
 
# Wait for time (ms)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"time": 2000}'

Execute JavaScript

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_evaluate \
  -p '{"function": "return document.title"}'

Multi-Step Playwright Code

For complex workflows, use browser_run_code to run multiple actions in one call:

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_run_code \
  -p '{"code": "async (page) => { await page.goto(\"https://example.com\"); await page.click(\"text=Learn more\"); return await page.title(); }"}'

Tip: Use browser_run_code for complex multi-step operations that should be atomic (all-or-nothing).

Workflow: Form Submission

Navigate to page
Get snapshot to find element refs
Fill form fields using refs
Click submit
Wait for confirmation
Screenshot result

Workflow: Data Extraction

Navigate to page
Get snapshot (contains text content)
Use browser_evaluate for complex extraction
Process results

Verification

Run: python3 scripts/verify.py

Expected: ✓ Playwright MCP server running

If Verification Fails

Run diagnostic: pgrep -f "@playwright/mcp"
Check: Server process running on port 8808
Try: bash scripts/start-server.sh
Stop and report if still failing - do not proceed with downstream steps

Tool Reference

See references/playwright-tools.md for complete tool documentation.

Troubleshooting

Issue	Solution
Element not found	Run browser_snapshot first to get current refs
Click fails	Try browser_hover first, then click
Form not submitting	Use `"submit": true` with browser_type
Page not loading	Increase wait time or use browser_wait_for
Server not responding	Stop and restart: `bash scripts/stop-server.sh && bash scripts/start-server.sh`

Browser Automation

Automate browser interactions via Playwright MCP server.

Server Lifecycle

Start Server

# Using helper script (recommended)
bash scripts/start-server.sh
 
# Or manually
npx @playwright/mcp@latest --port 8808 --shared-browser-context &

Stop Server

# Using helper script (closes browser first)
bash scripts/stop-server.sh
 
# Or manually
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_close -p '{}'
pkill -f "@playwright/mcp"

When to Stop

End of task: Stop when browser work is complete
Long sessions: Keep running if doing multiple browser tasks
Errors: Stop and restart if browser becomes unresponsive

Important: The --shared-browser-context flag is required to maintain browser state across multiple mcp-client.py calls. Without it, each call gets a fresh browser context.

Quick Reference

# Go to URL
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate \
  -p '{"url": "https://example.com"}'
 
# Go back
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate_back -p '{}'

Get Page State

# Accessibility snapshot (returns element refs for clicking/typing)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'
 
# Screenshot
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_take_screenshot \
  -p '{"type": "png", "fullPage": true}'

Interact with Elements

Use ref from snapshot output to target elements:

# Click element
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click \
  -p '{"element": "Submit button", "ref": "e42"}'
 
# Type text
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_type \
  -p '{"element": "Search input", "ref": "e15", "text": "hello world", "submit": true}'
 
# Fill form (multiple fields)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_fill_form \
  -p '{"fields": [{"ref": "e10", "value": "john@example.com"}, {"ref": "e12", "value": "password123"}]}'
 
# Select dropdown
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_select_option \
  -p '{"element": "Country dropdown", "ref": "e20", "values": ["US"]}'

Wait for Conditions

# Wait for text to appear
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"text": "Success"}'
 
# Wait for time (ms)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"time": 2000}'

Execute JavaScript

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_evaluate \
  -p '{"function": "return document.title"}'

Multi-Step Playwright Code

For complex workflows, use browser_run_code to run multiple actions in one call:

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_run_code \
  -p '{"code": "async (page) => { await page.goto(\"https://example.com\"); await page.click(\"text=Learn more\"); return await page.title(); }"}'

Tip: Use browser_run_code for complex multi-step operations that should be atomic (all-or-nothing).

Workflow: Form Submission

Navigate to page
Get snapshot to find element refs
Fill form fields using refs
Click submit
Wait for confirmation
Screenshot result

Workflow: Data Extraction

Navigate to page
Get snapshot (contains text content)
Use browser_evaluate for complex extraction
Process results

Verification

Run: python3 scripts/verify.py

Expected: ✓ Playwright MCP server running

If Verification Fails

Run diagnostic: pgrep -f "@playwright/mcp"
Check: Server process running on port 8808
Try: bash scripts/start-server.sh
Stop and report if still failing - do not proceed with downstream steps

Tool Reference

See references/playwright-tools.md for complete tool documentation.

Troubleshooting

Issue	Solution
Element not found	Run browser_snapshot first to get current refs
Click fails	Try browser_hover first, then click
Form not submitting	Use `"submit": true` with browser_type
Page not loading	Increase wait time or use browser_wait_for
Server not responding	Stop and restart: `bash scripts/stop-server.sh && bash scripts/start-server.sh`

browsing-with-playwright

Documentation

Documentation

Browser Automation

Server Lifecycle

Start Server

Stop Server

When to Stop

Quick Reference

Navigation

Get Page State

Interact with Elements

Wait for Conditions

Execute JavaScript

Multi-Step Playwright Code

Workflow: Form Submission

Workflow: Data Extraction

Verification

If Verification Fails

Tool Reference

Troubleshooting

Documentation

browsing-with-playwright

Documentation

Browser Automation

Server Lifecycle

Start Server

Stop Server

When to Stop

Quick Reference

Navigation

Get Page State

Interact with Elements

Wait for Conditions

Execute JavaScript

Multi-Step Playwright Code

Workflow: Form Submission

Workflow: Data Extraction

Verification

If Verification Fails

Tool Reference

Troubleshooting