Skip to content

MCP Browser Automation

This guide enables browser automation through the local Dockerized Playwright MCP server registered in .mcp.json.

Scope

Current implementation in this repository provides:

  • Docker-only MCP transport
  • Pinned immutable image digest
  • Standard MCP lifecycle via just mcp-health and just mcp-update

Current image: mcr.microsoft.com/playwright/mcp:latest

1. Validate MCP server wiring

Run from the hermetic Nix shell:

just sync-ai
just mcp-health

Expected summary line includes:

  • playwright MCP docker image: mcr.microsoft.com/playwright/mcp@sha256:<digest>

2. Use browser automation through MCP

In your MCP-capable client, run prompts similar to:

Use the playwright MCP server to open https://mail.google.com and report
whether the page is a signed-in inbox view or a sign-in prompt.

Use the playwright MCP server to navigate to https://example.com,
click the first primary button, and return a screenshot.

3. Authenticated session strategy

For authenticated flows such as Gmail:

  • Treat account credentials and recovery secrets as vault-managed secrets.
  • Retrieve secrets via Bitwarden MCP when needed.
  • Avoid storing raw credentials in repository files.

Reference pattern: Bitwarden Hello World.

Current limitations

The upstream Playwright MCP Docker image defaults to headless Chromium. This is sufficient for deterministic navigation and interaction, but does not support a persistent headed browser profile for long-lived authenticated sessions.

Troubleshooting

  • just mcp-health fails on digest format: run just mcp-update and re-run health checks.
  • Docker manifest fetch fails: verify local Docker daemon access and outbound network connectivity.
  • Browser automation fails on a specific site: retry with a simpler deterministic sequence (navigate, wait, click, snapshot) before escalating to a more complex task prompt.