# MCP Playwright Server
[](https://www.typescriptlang.org/)[](https://playwright.dev/)[](https://modelcontextprotocol.io/)[](https://nodejs.org/)[](LICENSE)
A comprehensive **Model Context Protocol (MCP) server** for browser automation using Playwright. This server enables AI assistants to control browsers via the MCP protocol, providing powerful tools for web testing, accessibility audits, and browser automation.
## Features
- 🌐 **Multi-Browser Support** - Chromium, Firefox, and WebKit
- 🔧 **50+ Browser Automation Tools** - Navigation, interaction, assertions, screenshots
- ♿ **Accessibility Testing** - Built-in axe-core integration with WCAG compliance checks
- 🔒 **Session Management** - Isolated browser contexts with rate limiting
- 📸 **Visual Testing** - Screenshots, video recording, and tracing
- 🧪 **AI Test Agents** - Automated test planning, generation, and healing
## Technology Stack
| Category | Technologies |
| ---------------------- | -------------------------------- |
| **Runtime** | Node.js 18+ |
| **Language** | TypeScript 5.8 |
| **Browser Automation** | Playwright 1.52+ |
| **Protocol** | Model Context Protocol (MCP) SDK |
| **Validation** | Zod |
| **Accessibility** | @axe-core/playwright |
| **Logging** | Winston |
| **Testing** | @playwright/test |
| **Linting** | ESLint 9, Prettier |
## Architecture
```text
AI Client → MCP Protocol → Tool Handler → BrowserManager → Action Module → Playwright API
↑
SessionManager (lifecycle, rate limiting)
```
### Layer Responsibilities
| Layer | Location | Purpose |
| --------------- | ----------------------------------- | ------------------------------------------- |
| Entry | `src/index.ts` | Bootstrap, graceful shutdown |
| MCP Server | `src/server/mcp-server.ts` | Tool/resource registration, session cleanup |
| Handlers | `src/server/handlers/` | Tool definitions grouped by category |
| Browser Manager | `src/playwright/browser-manager.ts` | Orchestrates action modules |
| Actions | `src/playwright/actions/` | Domain-specific Playwright operations |
| Session Manager | `src/playwright/session-manager.ts` | Session/page lifecycle, rate limiting |
## Getting Started
### Prerequisites
- Node.js 18 or higher
- npm or yarn
### Installation
```bash
# Clone the repository
git clone https://github.com/j0hanz/playwright-mcp.git
cd playwright-mcp
# Install dependencies
npm install
# Install Playwright browsers
npm run install:browsers
```
### Configuration
Create a `.env` file in the project root (optional):
```env
LOG_LEVEL=info # debug, info, warn, error
DEFAULT_BROWSER=chromium # chromium, firefox, webkit
HEADLESS=true # Run headless mode
MAX_SESSIONS=5 # Concurrent sessions (1-20)
SESSION_TIMEOUT=1800000 # Session expiry in ms (30 min)
TIMEOUT_ACTION=20000 # Element action timeout in ms
TIMEOUT_NAVIGATION=30000 # Page navigation timeout in ms
```
### Running the Server
```bash
# Development mode (with hot reload)
npm run dev
# Production build and run
npm run build
npm start
```
## Project Structure
```text
├── src/
│ ├── index.ts # Application entry point
│ ├── config/
│ │ ├── server-config.ts # Environment configuration
│ │ └── types.ts # TypeScript type definitions
│ ├── server/
│ │ ├── mcp-server.ts # MCP server implementation
│ │ └── handlers/ # Tool handler categories
│ │ ├── browser-tools.ts # Browser lifecycle tools
│ │ ├── navigation-tools.ts # Navigation tools
│ │ ├── interaction-tools.ts# Click, fill, hover tools
│ │ ├── assertion-tools.ts # Web-first assertions
│ │ ├── page-tools.ts # Screenshots, content, a11y
│ │ ├── test-tools.ts # Test file management
│ │ ├── advanced-tools.ts # Network, tracing, dialogs
│ │ └── schemas.ts # Zod validation schemas
│ ├── playwright/
│ │ ├── browser-manager.ts # Central browser orchestration
│ │ ├── session-manager.ts # Session lifecycle
│ │ ├── browser-launcher.ts # Browser launch logic
│ │ └── actions/ # Domain-specific actions
│ │ ├── assertion-actions.ts
│ │ ├── interaction-actions.ts
│ │ ├── navigation-actions.ts
│ │ └── ...
│ └── utils/
│ ├── error-handler.ts # Centralized error handling
│ └── logger.ts # Winston logger
├── tests/ # Playwright test files
├── specs/ # Human-readable test plans
├── .github/
│ ├── agents/ # AI agent definitions
│ ├── prompts/ # Agent prompts
│ └── copilot-instructions.md # Development guidelines
└── playwright.config.ts # Playwright test configuration
```
## Available Tools
### Browser Lifecycle
| Tool | Description |
| --------------------- | ------------------------------------------------------------------- |
| `browser_launch` | Launch browser (Chromium, Firefox, WebKit) with optional auth state |
| `browser_close` | Close browser session |
| `browser_tabs` | List, create, close, or select browser tabs |
| `sessions_list` | List all active browser sessions |
| `save_storage_state` | Save cookies/localStorage for auth reuse |
| `session_reset_state` | Clear session data for test isolation |
### Navigation
| Tool | Description |
| ------------------ | ------------------------------ |
| `browser_navigate` | Navigate to URL |
| `browser_history` | Go back/forward in history |
| `browser_reload` | Reload current page |
| `handle_dialog` | Accept/dismiss browser dialogs |
### Interaction
| Tool | Description |
| ---------------- | ---------------------------------------------- |
| `element_click` | Click by role, text, testid, or selector |
| `element_fill` | Fill inputs by label, placeholder, or selector |
| `element_hover` | Hover over elements |
| `select_option` | Select dropdown options |
| `keyboard_press` | Press keys (Enter, Tab, shortcuts) |
| `keyboard_type` | Type text character by character |
| `checkbox_set` | Check/uncheck checkboxes |
| `file_upload` | Upload files |
| `drag_and_drop` | Drag and drop elements |
### Assertions
| Tool | Description |
| ------------------ | ------------------------------------------------- |
| `assert_element` | Assert state (visible, hidden, enabled, disabled) |
| `assert_text` | Assert element text content |
| `assert_value` | Assert input value |
| `assert_url` | Assert page URL |
| `assert_title` | Assert page title |
| `assert_attribute` | Assert element attribute |
| `assert_css` | Assert CSS property |
| `assert_checked` | Assert checkbox state |
| `assert_count` | Assert element count |
### Page Operations
| Tool | Description |
| -------------------------- | ------------------------------------------------ |
| `page_screenshot` | Capture screenshots (full page, element, region) |
| `page_pdf` | Generate PDF from page (Chromium only) |
| `page_content` | Get HTML and text content |
| `page_evaluate` | Execute JavaScript (read-only) |
| `wait_for_selector` | Wait for elements |
| `page_wait_for_load_state` | Wait for page load |
| `accessibility_scan` | Run axe-core accessibility audit |
| `browser_snapshot` | Get accessibility tree snapshot |
### Cookie Management
| Tool | Description |
| --------------- | ------------------------------------- |
| `cookies_get` | Retrieve cookies from browser context |
| `cookies_set` | Add cookies (auth tokens, sessions) |
| `cookies_clear` | Clear all or specific cookies |
### Advanced
| Tool | Description |
| -------------------------------- | ------------------------ |
| `network_mock` | Mock network responses |
| `network_unroute` | Remove network mocks |
| `tracing_start` / `tracing_stop` | Record execution traces |
| `console_capture` | Capture console messages |
| `har_record_start` | Record HTTP archive |
| `clock_install` | Control time in tests |
| `video_path` | Get video recording path |
## Best Practices for Stable Tests
Following these practices will ensure your tests are resilient, maintainable, and less prone to flakiness. See the full [Best Practices Guide](./docs/best-practices.md) for detailed examples.
### Core Principles
1. **Use Semantic, User-Facing Locators**
- Role-based locators are most reliable: `getByRole('button', { name: 'Submit' })`
- Avoid CSS selectors and XPath — these break when styling changes
- Priority: Role → Label → Placeholder → Text → TestId → CSS (last resort)
2. **Use Locator Chaining and Filtering**
- Chain locators to narrow searches: `page.getByRole('listitem').filter({ hasText: 'Product 2' })`
- Filter by text or other locators for dynamic content
- This reduces strict mode violations and increases clarity
3. **Always Use Web-First Assertions**
- Use `expect()` assertions which auto-wait: `await expect(page.getByText('Success')).toBeVisible()`
- Don't use direct checks like `isVisible()` without expect
- Assertions wait up to 5 seconds (configurable) before failing
4. **Avoid Common Pitfalls**
- ❌ `waitForTimeout()` — use specific waits instead
- ❌ `waitForLoadState('networkidle')` — use `'domcontentloaded'` or wait for elements
- ❌ CSS class selectors — use role/label/text locators
- ❌ Screenshots as selectors — use `browser_snapshot` for finding elements
- ❌ `test.only()` or `test.skip()` — remove before committing
### Example: Good Test Structure
```typescript
test('Add todo and verify', async ({ page }) => {
// Navigate
await page.goto('/');
// Get accessibility snapshot to understand page structure
const snapshot = await page.accessibility.snapshot();
// Interact using semantic locators (role > label > text)
await page.getByPlaceholder('What needs to be done?').fill('Buy groceries');
await page.getByRole('button', { name: 'Add' }).click();
// Verify using web-first assertions (auto-wait)
await expect(page.getByText('Buy groceries')).toBeVisible();
await expect(page.getByRole('listitem')).toHaveCount(1);
});
```
## Locator Priority
When interacting with elements, prefer user-facing locators (most reliable first):
1. **Role** ⭐ - `element_click(locatorType: 'role', role: 'button', name: 'Submit')`
2. **Label** ⭐ - `element_fill(locatorType: 'label', value: 'Email', text: '...')`
3. **Text** - `element_click(locatorType: 'text', value: 'Learn more')`
4. **Placeholder** - `element_fill(locatorType: 'placeholder', value: 'Search...')`
5. **TestId** - `element_click(locatorType: 'testid', value: 'submit-btn')`
6. **Selector** - CSS selector (last resort only)
## Development Workflow
```bash
# Watch mode with hot reload
npm run dev
# Build TypeScript to dist/
npm run build
# Run ESLint
npm run lint
npm run lint:fix
# Type check without emit
npm run type-check
# Format with Prettier
npm run format
# Run tests
npm test
npm run test:ui # Interactive UI
npm run test:headed # Visible browser
npm run test:debug # Debug mode
```
**Before committing:** Run `npm run lint && npm run type-check && npm run build`
## Coding Standards
### Tool Registration Pattern
```typescript
server.registerTool(
'tool_name',
{
title: 'Human Title',
description: 'What this tool does',
inputSchema: {
/* Zod schemas */
},
outputSchema: {
/* Result shape */
},
},
createToolHandler(async (input) => {
const result = await browserManager.someMethod(input);
return {
content: [{ type: 'text', text: 'Human readable' }],
structuredContent: result, // Machine readable
};
}, 'Error prefix message')
);
```
### Action Module Pattern
```typescript
export class MyActions extends BaseAction {
async myOperation(sessionId: string, pageId: string, options: Options) {
return this.executePageOperation(
sessionId,
pageId,
'My operation',
async (page) => {
// Playwright operations
return { success: true, data: '...' };
}
);
}
}
```
### Error Handling
```typescript
import {
ErrorCode,
ErrorHandler,
validateUUID,
} from '../utils/error-handler.js';
validateUUID(sessionId, 'sessionId'); // Throws on invalid
throw ErrorHandler.sessionNotFound(id); // Factory methods
throw ErrorHandler.handlePlaywrightError(e); // Maps Playwright errors
```
## Testing
Tests use `@playwright/test` framework. Configuration is in `playwright.config.ts`.
```bash
npm test # Run all tests
npm run test:ui # Interactive test UI
npm run test:headed # With visible browser
npm run test:debug # Debug mode with inspector
npm run test:trace # Record traces
npm run test:report # Show HTML report
```
### Test Configuration
- **Timeout**: 30 seconds per test
- **Retries**: 2 on CI, 0 locally
- **Browsers**: Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari
- **Viewport**: 1366x900
- **Test ID Attribute**: `data-testid`
## AI Test Agents
Three AI agents for automated test workflows:
| Agent | Input | Output |
| ------------- | ------------------- | ----------------------- |
| **Planner** | App URL + seed test | `specs/*.md` test plans |
| **Generator** | Test plan | `tests/*.spec.ts` files |
| **Healer** | Failing test | Fixed test file |
### Usage
1. **Planner**: Explore app and create test plans in `specs/`
2. **Generator**: Transform plans into Playwright tests
3. **Healer**: Debug and fix failing tests
Agent definitions are in `.github/agents/` with prompts in `.github/prompts/`.
## Security
- **URL validation**: Only `http://` and `https://` protocols allowed
- **UUID validation**: All session/page IDs validated
- **Rate limiting**: Configurable `MAX_SESSIONS_PER_MINUTE`
- **Session isolation**: Each browser context is isolated
- **Script restrictions**: Only safe, read-only JavaScript evaluation
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Follow the coding standards in `.github/copilot-instructions.md`
4. Run linting and type checking (`npm run lint && npm run type-check`)
5. Ensure tests pass (`npm test`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
### Adding a New Tool
1. Add method to action class in `src/playwright/actions/`
2. Register in handler file in `src/server/handlers/`
3. Add schemas to `schemas.ts` if new input shapes needed
4. Add tests for the new functionality
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Playwright](https://playwright.dev/) - Browser automation framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - AI assistant protocol
- [axe-core](https://github.com/dequelabs/axe-core) - Accessibility testing engine
