{"id":33314503,"url":"https://github.com/rashaideh93/playwright-mcp-server","last_synced_at":"2025-11-19T12:03:13.750Z","repository":{"id":324182447,"uuid":"1096250635","full_name":"rashaideh93/playwright-mcp-server","owner":"rashaideh93","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-14T08:19:02.000Z","size":199,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-14T09:25:47.546Z","etag":null,"topics":["automation","browser-automation","mcp","playwright","qa","testing"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rashaideh93.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-14T06:36:04.000Z","updated_at":"2025-11-14T08:19:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rashaideh93/playwright-mcp-server","commit_stats":null,"previous_names":["rashaideh93/playwright-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rashaideh93/playwright-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashaideh93%2Fplaywright-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashaideh93%2Fplaywright-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashaideh93%2Fplaywright-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashaideh93%2Fplaywright-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rashaideh93","download_url":"https://codeload.github.com/rashaideh93/playwright-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rashaideh93%2Fplaywright-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285240542,"owners_count":27137943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-19T02:00:05.673Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","browser-automation","mcp","playwright","qa","testing"],"created_at":"2025-11-19T12:00:57.441Z","updated_at":"2025-11-19T12:03:13.744Z","avatar_url":"https://github.com/rashaideh93.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Playwright MCP Server\n\nAn MCP (Model Context Protocol) server that exposes Playwright automation capabilities through a standardized protocol interface. This allows AI applications to control web browsers and interact with web pages programmatically.\n\n## Overview\n\nThis MCP server integrates the popular Playwright automation library with the Model Context Protocol, enabling seamless browser automation through AI assistants and other MCP clients.\n\n### Supported Browsers\n- **Chromium** - Full Chromium support\n- **Firefox** - Mozilla Firefox support\n- **WebKit** - Safari/WebKit support\n\n## Features\n\nThe server exposes the following tools:\n\n### Browser Management\n- **launch_browser** - Launch a new browser instance with optional URL navigation\n- **close_browser** - Close an existing browser instance and clean up resources\n\n### Page Navigation\n- **navigate** - Navigate to a specific URL with configurable wait conditions\n- **get_url** - Retrieve the current URL of the active page\n- **wait_for_navigation** - Wait for a page navigation to complete\n\n### Element Interaction\n- **click_element** - Click an element using CSS selector\n- **fill_input** - Fill input fields with text\n- **get_text** - Get text content from an element\n\n### Page Inspection\n- **get_title** - Get the current page title\n- **screenshot** - Take a screenshot of the current page\n\n## Installation\n\n### Prerequisites\n- Node.js 17 or higher\n- npm or yarn package manager\n\n### Install from NPM (Recommended)\n\nThe easiest way to get started is to install from NPM:\n\n```bash\nnpm install playwright-mcp-rashaideh93\n```\n\nThen start the server:\n```bash\nnpx playwright-mcp-rashaideh93\n```\n\n### Setup from Source\n\nAlternatively, you can clone and build from source:\n\n1. **Clone or download the project:**\n   ```bash\n   git clone https://github.com/rashaideh93/playwright-mcp-server.git\n   cd playwright-mcp-server\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n3. **Build the TypeScript code:**\n   ```bash\n   npm run build\n   ```\n\n## Usage\n\n### Quick Start\n\n**For Users:**\n```bash\nnpm install playwright-mcp-rashaideh93\nnpx playwright-mcp-rashaideh93\n```\n\n**For Developers:**\n```bash\ngit clone https://github.com/rashaideh93/playwright-mcp-server.git\ncd playwright-mcp-server\nnpm install\nnpm test        # Run validation tests\nnpm run build   # Compile TypeScript\nnpm start       # Start the server\n```\n\n### Starting the Server\n\n```bash\nnpm start\n```\n\nOr in development mode with auto-rebuild:\n```bash\nnpm run dev\n```\n\n### Connecting to the Server\n\n#### VS Code with GitHub Copilot\n\n1. Open VS Code and press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)\n2. Select **MCP: Add server...**\n3. Choose **Stdio** and enter the command:\n   ```\n   node ./build/index.js\n   ```\n4. Give it a name like \"Playwright MCP\"\n\n#### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/playwright-mcp-server/build/index.js\"]\n    }\n  }\n}\n```\n\n#### Other MCP Clients\n\nConfigure your MCP client to connect to this server using stdio transport on the node build/index.js command.\n\n## Tool Usage Examples\n\n### Example 1: Basic Navigation and Screenshot\n\n```\n1. launch_browser with browserType: \"chromium\", headless: true, url: \"https://example.com\"\n   → Returns: browser-1\n\n2. screenshot with browserId: \"browser-1\", filename: \"example.png\"\n   → Screenshot saved\n\n3. close_browser with browserId: \"browser-1\"\n   → Browser closed\n```\n\n### Example 2: Form Filling\n\n```\n1. launch_browser with browserType: \"chromium\"\n   → Returns: browser-1\n\n2. navigate with browserId: \"browser-1\", url: \"https://example.com/form\"\n\n3. fill_input with browserId: \"browser-1\", selector: \"input[name='username']\", text: \"myuser\"\n\n4. fill_input with browserId: \"browser-1\", selector: \"input[name='password']\", text: \"mypass\"\n\n5. click_element with browserId: \"browser-1\", selector: \"button[type='submit']\"\n\n6. close_browser with browserId: \"browser-1\"\n```\n\n### Example 3: Content Extraction\n\n```\n1. launch_browser with browserType: \"chromium\", url: \"https://news.example.com\"\n   → Returns: browser-1\n\n2. get_title with browserId: \"browser-1\"\n   → Returns page title\n\n3. get_text with browserId: \"browser-1\", selector: \".article-title\"\n   → Returns article title text\n\n4. close_browser with browserId: \"browser-1\"\n```\n\n## Architecture\n\n### Browser Instance Management\n\n- Each browser instance is assigned a unique ID (e.g., `browser-1`, `browser-2`)\n- Browser instances include:\n  - The browser process\n  - A default browser context\n  - A default page\n- Instances are stored in memory and cleaned up when closed\n\n### Tool Parameters\n\nAll tools use **Zod** for schema validation, ensuring type-safe inputs and clear error messages.\n\n### Error Handling\n\nThe server gracefully handles errors and returns meaningful error messages:\n- Invalid browser IDs\n- Navigation timeouts\n- Element not found errors\n- Playwright runtime errors\n\n### Testing\n\nThe server includes Jest for developers to write unit tests:\n\n```bash\nnpm test              # Run all tests\nnpm run test:watch   # Watch mode (auto-rerun on changes)\nnpm run test:coverage # Generate coverage report\n```\n\n**For Developers:**\nSee [DEVELOPER_TESTING_GUIDE.md](DEVELOPER_TESTING_GUIDE.md) for:\n- How to write unit tests for your code\n- Example test files\n- Testing best practices\n- Jest configuration and commands\n- Running specific tests\n\n## Development\n\n### Project Structure\n\n```\nplaywright-mcp-server/\n├── src/\n│   └── index.ts           # Main server implementation\n├── build/                 # Compiled JavaScript (generated)\n├── .vscode/\n│   └── mcp.json          # MCP server configuration\n├── package.json          # Project dependencies\n├── tsconfig.json         # TypeScript configuration\n└── README.md             # This file\n```\n\n### Building\n\n```bash\nnpm run build\n```\n\nThis compiles TypeScript to JavaScript and makes the script executable.\n\n### Testing\n\nThe server can be tested using the MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node ./build/index.js\n```\n\nThis opens a web interface where you can:\n- Test individual tools\n- Inspect tool schemas\n- View tool outputs\n- Debug server behavior\n\n## Integration with AI Applications\n\n### GitHub Copilot in VS Code\n\nOnce connected, Copilot can:\n- Control browsers through natural language\n- Perform automated testing\n- Extract data from web pages\n- Fill forms and interact with web applications\n\n### Claude (Anthropic)\n\nWhen configured in Claude Desktop:\n- Use natural language to script browser interactions\n- Automate web scraping tasks\n- Generate test scripts\n- Create end-to-end automation workflows\n\n### Other Clients\n\nAny MCP-compatible client can use these browser automation tools:\n- LM Studio\n- Cursor\n- Windsurf\n- Cline\n- And others in the MCP ecosystem\n\n## Advanced Configuration\n\n### Browser Launch Options\n\nThe `launch_browser` tool accepts:\n- `browserType` - \"chromium\", \"firefox\", or \"webkit\"\n- `headless` - Run in headless mode (default: true)\n- `url` - Optional URL to navigate to immediately\n\n### Navigation Wait Conditions\n\nThe `navigate` tool supports:\n- `\"load\"` - Wait for the load event (default)\n- `\"domcontentloaded\"` - Wait for DOM content loaded\n- `\"networkidle\"` - Wait for network to be idle\n\n## Troubleshooting\n\n### Server Won't Start\n- Ensure Node.js 17+ is installed\n- Check that all dependencies are installed: `npm install`\n- Verify the build succeeded: `npm run build`\n\n### Connection Issues\n- Verify the absolute path in mcp.json is correct\n- Check that the build folder exists and contains `index.js`\n- Look for stderr output for connection errors\n\n### Tool Execution Errors\n- Ensure the browser ID is valid\n- Verify CSS selectors are correct\n- Check that elements exist before interaction\n- Review Playwright documentation for specific element interactions\n\n### Performance\n- Headless mode is faster than headed mode\n- Close browsers when done to free resources\n- Use appropriate wait conditions for navigation\n- Consider browser context cleanup for long-running sessions\n\n## API Reference\n\n### Tool: launch_browser\n\n**Description:** Launch a new browser instance\n\n**Parameters:**\n- `browserType` (enum: \"chromium\" | \"firefox\" | \"webkit\") - Browser to launch\n- `headless` (boolean, optional, default: true) - Headless mode\n- `url` (string, optional) - URL to navigate to\n\n**Returns:** Browser ID string\n\n### Tool: navigate\n\n**Description:** Navigate to a URL\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n- `url` (string) - URL to navigate to\n- `waitUntil` (enum: \"load\" | \"domcontentloaded\" | \"networkidle\", optional, default: \"load\")\n\n**Returns:** Navigation result\n\n### Tool: click_element\n\n**Description:** Click an element\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n- `selector` (string) - CSS selector\n\n**Returns:** Click result\n\n### Tool: fill_input\n\n**Description:** Fill an input field\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n- `selector` (string) - CSS selector of input\n- `text` (string) - Text to fill\n\n**Returns:** Fill result\n\n### Tool: get_text\n\n**Description:** Get text content\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n- `selector` (string) - CSS selector\n\n**Returns:** Text content\n\n### Tool: get_title\n\n**Description:** Get page title\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n\n**Returns:** Page title\n\n### Tool: get_url\n\n**Description:** Get current URL\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n\n**Returns:** Current URL\n\n### Tool: screenshot\n\n**Description:** Take a screenshot\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n- `filename` (string, optional) - Output filename\n\n**Returns:** Screenshot path\n\n### Tool: wait_for_navigation\n\n**Description:** Wait for navigation\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n- `timeout` (number, optional, default: 30000) - Timeout in ms\n\n**Returns:** Navigation completion result\n\n### Tool: close_browser\n\n**Description:** Close a browser\n\n**Parameters:**\n- `browserId` (string) - Browser instance ID\n\n**Returns:** Close result\n\n## Dependencies\n\n- **@modelcontextprotocol/sdk** - MCP protocol implementation\n- **playwright** - Browser automation library\n- **zod** - Runtime type validation\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.\n\n## Resources\n\n- [MCP Documentation](https://modelcontextprotocol.io/)\n- [Playwright Documentation](https://playwright.dev/)\n- [MCP GitHub Repository](https://github.com/modelcontextprotocol/)\n- [Playwright GitHub Repository](https://github.com/microsoft/playwright)\n\n## Support\n\nFor issues, questions, or suggestions:\n1. Check the Playwright documentation for browser-specific issues\n2. Review MCP documentation for protocol-related questions\n3. Consult the troubleshooting section above\n4. Open an issue on the GitHub repository\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frashaideh93%2Fplaywright-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frashaideh93%2Fplaywright-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frashaideh93%2Fplaywright-mcp-server/lists"}