# Playwright MCP — Setup Guide for Amazon Quick Desktop

> **What is Playwright MCP?**  
> Playwright MCP is Microsoft's official MCP server that gives Amazon Quick the ability to control a real Chromium browser — navigate pages, click elements, fill forms, take screenshots, run JavaScript, and more — all through structured accessibility snapshots (no vision model needed).

---

## Prerequisites

| Requirement | How to Check |
|---|---|
| **Amazon Quick Desktop** | Already installed and running |
| **Node.js 18+** | Open a terminal and run `node --version`. If not installed, download from [nodejs.org](https://nodejs.org/) |
| **npx** (comes with Node.js) | Run `npx --version` — should return a version number |

---

## Step 1 — Install the Playwright MCP Package (Optional Pre-Install)

The MCP server can auto-install on first use via `npx`, but if you want to pre-install it globally:

```bash
npm install -g @playwright/mcp
```

Then download the browser binaries:

```bash
npx playwright install
```

> **Note:** If you skip this step, Amazon Quick will auto-download the server via `npx` on first use. The browser binaries will also be pulled automatically. First-run may take a minute.

---

## Step 2 — Add the MCP Server in Amazon Quick

1. Open **Amazon Quick Desktop**
2. In the sidebar, click **Settings** (gear icon at the bottom)
3. Navigate to **Capabilities** → **Connections** tab
4. Scroll down to **Advanced Integrations**
5. Click **"+ Add MCP / Skill"**
6. Fill in the configuration:

| Field | Value |
|---|---|
| **Name** | `playwrite-mcp` (or any name you prefer) |
| **Transport** | `stdio` |
| **Command** | `npx` |
| **Arguments** | `@playwright/mcp@latest` |

7. Click **Save**

### Full JSON Configuration (for reference)

If your setup flow asks for raw JSON, use this:

```json
{
  "mcpServers": {
    "playwrite-mcp": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}
```

---

## Step 3 — Verify the Connection

1. After saving, the MCP server should appear in your **Capabilities → Connections** list with a connected status
2. Start a **new conversation** in Amazon Quick
3. Test it by asking:

> *"Navigate to https://example.com and take a screenshot"*

You should see a Chromium browser window open, navigate to the page, and Amazon Quick will return the results.

---

## Optional Configuration

### Run Headless (No Visible Browser Window)

If you don't want to see the browser pop up, add `--headless` to the arguments:

| Field | Value |
|---|---|
| **Arguments** | `@playwright/mcp@latest --headless` |

### Choose a Different Browser

By default Playwright uses Chromium. To use a different browser:

| Browser | Arguments Value |
|---|---|
| Chrome | `@playwright/mcp@latest --browser=chrome` |
| Firefox | `@playwright/mcp@latest --browser=firefox` |
| Edge | `@playwright/mcp@latest --browser=msedge` |
| WebKit (Safari) | `@playwright/mcp@latest --browser=webkit` |

### Run as Standalone HTTP Server

For better performance or shared access, you can run the server as a standalone HTTP service:

**In a terminal:**
```bash
npx @playwright/mcp@latest --port 8931
```

**Then configure Amazon Quick with URL transport instead:**

| Field | Value |
|---|---|
| **Transport** | `url` (or `http`) |
| **URL** | `http://localhost:8931/mcp` |

---

## Available Tools (22 total)

Once connected, Amazon Quick gains these browser automation capabilities:

| Tool | Description |
|---|---|
| `browser_navigate` | Navigate to a URL |
| `browser_navigate_back` | Go back in history |
| `browser_click` | Click an element on the page |
| `browser_type` | Type text into an input field |
| `browser_fill_form` | Fill multiple form fields at once |
| `browser_press_key` | Press a keyboard key |
| `browser_select_option` | Select a dropdown option |
| `browser_hover` | Hover over an element |
| `browser_drag` | Drag and drop between elements |
| `browser_drop` | Drop files/data onto an element |
| `browser_file_upload` | Upload files to a file input |
| `browser_take_screenshot` | Capture a screenshot (PNG/JPEG) |
| `browser_snapshot` | Capture accessibility tree snapshot |
| `browser_evaluate` | Run JavaScript on the page |
| `browser_run_code` | Execute a Playwright code snippet |
| `browser_console_messages` | View browser console output |
| `browser_network_requests` | View network requests |
| `browser_handle_dialog` | Accept/dismiss browser dialogs |
| `browser_tabs` | Manage browser tabs (list, create, close, switch) |
| `browser_resize` | Resize the browser window |
| `browser_wait_for` | Wait for text or a timeout |
| `browser_close` | Close the browser page |

---

## Troubleshooting

| Problem | Solution |
|---|---|
| **"npx not found"** | Install Node.js from [nodejs.org](https://nodejs.org/) — npx comes bundled with it |
| **Server shows disconnected** | Open a terminal and run `npx @playwright/mcp@latest` manually to check for errors. Often a network issue on first download. |
| **Browser doesn't open** | Make sure you're not passing `--headless`. Default is headed (visible browser). |
| **"Browser closed" errors** | The browser may have been closed manually. Start a new conversation to get a fresh browser session. |
| **Slow first launch** | Normal — `npx` downloads the package and Playwright downloads browser binaries on first run. Subsequent launches are fast. |
| **Permission errors on Windows** | Run your terminal as Administrator, or ensure your user has write access to the npm cache folder |
| **Tools not appearing in conversation** | Start a **new conversation** after adding the MCP server. Existing conversations don't pick up new MCP tools. |

---

## Tips for Using Playwright MCP in Amazon Quick

- **Be specific with instructions** — e.g., "Click the blue 'Submit' button" rather than just "click submit"
- **Use accessibility snapshots** — Ask Quick to "take a snapshot" to see the page structure before interacting
- **Chain actions naturally** — "Go to google.com, search for 'Amazon Quick', and click the first result"
- **Screenshots for verification** — Ask for a screenshot after actions to confirm they worked
- **Form filling** — You can fill entire forms in one request: "Fill in the name as 'Jon', email as 'jon@example.com', and click Submit"

---

## Quick Reference

```
Name:       playwrite-mcp
Transport:  stdio
Command:    npx
Arguments:  @playwright/mcp@latest
```

That's it! Once configured, just ask Amazon Quick to browse the web and it will use Playwright to do it. 🎉