{"id":31663978,"url":"https://github.com/badchars/mcp-browser","last_synced_at":"2026-05-08T19:32:03.167Z","repository":{"id":315954528,"uuid":"1061375738","full_name":"badchars/mcp-browser","owner":"badchars","description":"MCP server for headless browser automation with Playwright - Non-commercial license","archived":false,"fork":false,"pushed_at":"2025-09-22T11:52:43.000Z","size":150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-19T02:34:56.167Z","etag":null,"topics":["ai-tools","browser-automation","bug-bounty","claude-desktop","javascript-analysis","mcp","model-context-protocol","penetration-testing","playwright","security-research","security-tools","vulnerability-scanner","web-security","xss-scanner"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/badchars.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","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-09-21T19:29:43.000Z","updated_at":"2025-09-22T11:52:47.000Z","dependencies_parsed_at":"2025-09-22T17:00:10.809Z","dependency_job_id":null,"html_url":"https://github.com/badchars/mcp-browser","commit_stats":null,"previous_names":["badchars/mcp-browser"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/badchars/mcp-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badchars%2Fmcp-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badchars%2Fmcp-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badchars%2Fmcp-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badchars%2Fmcp-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/badchars","download_url":"https://codeload.github.com/badchars/mcp-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/badchars%2Fmcp-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32794602,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"ssl_error","status_checked_at":"2026-05-08T08:22:45.650Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-tools","browser-automation","bug-bounty","claude-desktop","javascript-analysis","mcp","model-context-protocol","penetration-testing","playwright","security-research","security-tools","vulnerability-scanner","web-security","xss-scanner"],"created_at":"2025-10-07T20:52:50.284Z","updated_at":"2026-05-08T19:32:03.152Z","avatar_url":"https://github.com/badchars.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Browser\n\n[![Version](https://img.shields.io/badge/version-0.3.0-blue.svg)](https://github.com/badchars/mcp-browser)\n[![License](https://img.shields.io/badge/license-Non--Commercial-red.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node.js-%3E%3D18-green.svg)](https://nodejs.org/)\n[![Playwright](https://img.shields.io/badge/playwright-1.40.0-orange.svg)](https://playwright.dev/)\n\nA powerful Model Context Protocol (MCP) server that provides advanced browser automation capabilities using Playwright. This server enables AI assistants to control web browsers programmatically through a standardized MCP interface, with specialized features for **JavaScript analysis** and **XSS vulnerability scanning**.\n\n\u003e 🔒 **Perfect for Security Researchers, Penetration Testers, and Web Application Analysts**\n\n## 🚀 Key Features\n\n### 🔍 **Security Analysis \u0026 XSS Scanning**\n\n- **Interactive XSS Scanner**: Automatic detection and testing of XSS vulnerabilities\n- **Comprehensive XSS Detection**: Scans inline scripts, external scripts, HTML attributes, URL parameters, and form inputs\n- **Proof of Concept Generation**: Automatic PoC HTTP requests for confirmed vulnerabilities\n- **Alert Detection**: Real-time alert popup detection during XSS testing\n- **Detailed Vulnerability Reports**: JSON reports with severity levels and remediation suggestions\n\n### 📁 **JavaScript Files Analysis**\n\n- **Complete JS Fetching**: Download all JavaScript files (external, inline, dynamic)\n- **Smart File Organization**: Preserve directory structure from URLs\n- **Manifest Generation**: Detailed JSON manifest with file metadata\n- **URL Filtering**: Regex-based filtering for targeted analysis\n- **Performance API Integration**: Detect dynamically loaded scripts\n\n### 🔍 **Advanced API Endpoint Discovery**\n\n- **AST-Based Analysis**: Parse JavaScript with Babel for deep code analysis\n- **Network Call Detection**: Find fetch, axios, XMLHttpRequest, WebSocket calls\n- **Metadata Extraction**: Extract method, URL, headers, auth tokens, body schemas\n- **Request Spec Generation**: Auto-generate cURL, HTTPie, Postman examples\n- **Context Analysis**: Analyze surrounding code for better understanding\n- **Source Map Support**: Apply source maps for better code readability\n- **Dynamic Validation**: Test discovered endpoints in real browser environment\n\n### 🌐 **Advanced Browser Automation**\n\n- **Multi-browser Support**: Chromium, Firefox, and WebKit browsers\n- **Session Management**: Multiple browser sessions with unique IDs\n- **Navigation**: Navigate to URLs with configurable wait conditions\n- **Element Interaction**: Click, type, and interact with web elements\n- **Screenshots**: Capture full page or element screenshots\n- **Text Extraction**: Extract text content from web elements\n- **Form Automation**: Fill out forms with multiple fields\n- **JavaScript Execution**: Execute custom JavaScript on pages\n- **Mobile Emulation**: Emulate mobile devices and orientations\n- **PDF Generation**: Create PDFs from web pages\n- **File Downloads**: Download files from web pages\n- **Network Interception**: Monitor and mock network requests\n- **Performance Metrics**: Collect page performance data\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/badchars/mcp-browser.git\ncd mcp-browser\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Install Playwright browsers:\n\n```bash\nnpm run install-browsers\n```\n\n## Usage\n\n### Building the Project\n\nFirst, build the TypeScript project:\n\n```bash\nnpm run build\n```\n\nThis creates the `dist/index.js` file that will be used by the MCP server.\n\n### Available Tools\n\n#### Browser Navigation\n\n- `browser_navigate`: Navigate to a URL with configurable wait conditions\n- `browser_get_page_info`: Get current page information (URL, title, viewport)\n\n#### Element Interaction\n\n- `browser_click`: Click on elements using CSS selectors\n- `browser_type`: Type text into form fields\n- `browser_wait_for_element`: Wait for elements to appear\n- `browser_fill_form`: Fill out forms with multiple fields\n\n#### Content Extraction\n\n- `browser_extract_text`: Extract text content from elements\n- `browser_screenshot`: Take screenshots of pages or elements\n\n#### Page Manipulation\n\n- `browser_scroll`: Scroll pages in different directions\n- `browser_execute_script`: Execute custom JavaScript\n- `browser_mobile_emulate`: Emulate mobile devices\n\n#### File Operations\n\n- `browser_download_file`: Download files from web pages\n- `browser_create_pdf`: Generate PDFs from web pages\n- `browser_fetch_javascript_files`: Fetch and download all JavaScript files loaded by the web application\n\n#### Network Control\n\n- `browser_intercept_requests`: Monitor and mock network requests\n\n#### Session Management\n\n- `browser_close_session`: Close browser sessions\n\n## Configuration\n\n### MCP Server Configuration\n\nAdd the following to your MCP client configuration file:\n\n#### Production Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-browser\": {\n      \"command\": \"node\",\n      \"args\": [\"dist/index.js\"],\n      \"env\": {\n        \"NODE_ENV\": \"production\"\n      },\n      \"description\": \"MCP Browser server for headless browser automation with Playwright\"\n    }\n  }\n}\n```\n\n**Important**: Make sure to run `npm run build` before using this configuration.\n\n#### Development Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-browser\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"index.ts\"],\n      \"env\": {\n        \"NODE_ENV\": \"development\"\n      },\n      \"description\": \"MCP Browser server for headless browser automation with Playwright (Development Mode)\"\n    }\n  }\n}\n```\n\n### Browser Types\n\n- `chromium`: Default browser (recommended)\n- `firefox`: Mozilla Firefox\n- `webkit`: Safari engine\n\n### Session Management\n\n- Default session ID: `default`\n- Multiple sessions supported with unique IDs\n- Sessions persist until explicitly closed\n\n### Viewport Configuration\n\n- Default: 1280x720\n- Customizable per session\n- Mobile emulation includes device-specific viewports\n\n## 🔒 Security Analysis Use Cases\n\n### XSS Vulnerability Scanning\n\nPerfect for penetration testers and security researchers:\n\n```json\n{\n  \"name\": \"browser_interactive_xss_scan\",\n  \"arguments\": {\n    \"sessionId\": \"security_test\",\n    \"scanScripts\": true,\n    \"scanAttributes\": true,\n    \"scanUrls\": true,\n    \"scanForms\": true,\n    \"autoTestPoC\": true,\n    \"waitForAlert\": 3000,\n    \"outputFile\": \"./xss_scan_results.json\"\n  }\n}\n```\n\n### JavaScript Code Analysis\n\nIdeal for reverse engineering and code review:\n\n```json\n{\n  \"name\": \"browser_fetch_javascript_files\",\n  \"arguments\": {\n    \"downloadPath\": \"./js_analysis\",\n    \"includeInlineScripts\": true,\n    \"includeExternalScripts\": true,\n    \"includeDynamicScripts\": true,\n    \"preserveStructure\": true,\n    \"generateManifest\": true,\n    \"filterUrl\": \".*\\\\.js$\"\n  }\n}\n```\n\n### Advanced API Endpoint Discovery\n\nDeep analysis of JavaScript files to discover API endpoints:\n\n```json\n{\n  \"name\": \"browser_analyze_javascript_api_endpoints\",\n  \"arguments\": {\n    \"jsFilesPath\": \"./js_analysis\",\n    \"outputPath\": \"./api_discovery\",\n    \"includePrettify\": true,\n    \"includeSourceMaps\": true,\n    \"detectNetworkCalls\": true,\n    \"extractMetadata\": true,\n    \"generateRequestSpecs\": true,\n    \"validateEndpoints\": false,\n    \"contextLines\": 30\n  }\n}\n```\n\n**Note**: Both `jsFilesPath` and `outputPath` should use relative paths for MCP compatibility. The tool includes automatic fallback mechanisms for permission-restricted environments.\n\n### Network Traffic Monitoring\n\nMonitor and analyze web application behavior:\n\n```json\n{\n  \"name\": \"browser_log_network_requests\",\n  \"arguments\": {\n    \"filePath\": \"./network_analysis.json\",\n    \"includeHeaders\": true,\n    \"includeBody\": false,\n    \"filterUrl\": \".*api.*\"\n  }\n}\n```\n\n## Examples\n\n### Basic Navigation\n\n```json\n{\n  \"name\": \"browser_navigate\",\n  \"arguments\": {\n    \"url\": \"https://example.com\",\n    \"waitFor\": \"load\",\n    \"browser\": \"chromium\"\n  }\n}\n```\n\n### Element Interaction\n\n```json\n{\n  \"name\": \"browser_click\",\n  \"arguments\": {\n    \"selector\": \"#submit-button\",\n    \"waitFor\": 1000\n  }\n}\n```\n\n### Form Filling\n\n```json\n{\n  \"name\": \"browser_fill_form\",\n  \"arguments\": {\n    \"fields\": {\n      \"#username\": \"myuser\",\n      \"#password\": \"mypassword\"\n    },\n    \"submitSelector\": \"#login-button\"\n  }\n}\n```\n\n### Screenshot Capture\n\n```json\n{\n  \"name\": \"browser_screenshot\",\n  \"arguments\": {\n    \"path\": \"./screenshot.png\",\n    \"fullPage\": true\n  }\n}\n```\n\n### Mobile Emulation\n\n```json\n{\n  \"name\": \"browser_mobile_emulate\",\n  \"arguments\": {\n    \"device\": \"iPhone 12\",\n    \"orientation\": \"portrait\"\n  }\n}\n```\n\n### JavaScript Files Fetching\n\n```json\n{\n  \"name\": \"browser_fetch_javascript_files\",\n  \"arguments\": {\n    \"downloadPath\": \"./downloaded_scripts\",\n    \"includeInlineScripts\": true,\n    \"includeExternalScripts\": true,\n    \"includeDynamicScripts\": true,\n    \"preserveStructure\": true,\n    \"generateManifest\": true\n  }\n}\n```\n\n**Note**: Use relative paths (starting with `./`) for better compatibility with MCP file system restrictions. The tool will automatically fallback to the current working directory if permission is denied.\n\n## Development\n\n### Building for Production\n\n```bash\nnpm run build\n```\n\n### Running in Development Mode\n\n```bash\nnpm run dev\n```\n\n**Note**: This is for development only. For production use, always build the project first and use the production MCP server configuration.\n\n### TypeScript Configuration\n\nThe project uses TypeScript with strict type checking. Configuration is in `tsconfig.json`.\n\n### Linting\n\nESLint is configured with TypeScript support:\n\n```bash\nnpx eslint index.ts\n```\n\n## Architecture\n\n### Core Components\n\n- **MCPBrowserServer**: Main server class handling MCP protocol\n- **BrowserSession**: Manages individual browser sessions\n- **Tool Handlers**: Individual handlers for each browser operation\n\n### Session Management\n\n- Sessions are stored in a Map with unique IDs\n- Each session contains browser, context, and page instances\n- Sessions are automatically cleaned up on server shutdown\n\n### Error Handling\n\n- Comprehensive error handling for all browser operations\n- Graceful degradation when operations fail\n- Detailed error messages returned to clients\n\n## Dependencies\n\n- **@modelcontextprotocol/sdk**: MCP protocol implementation\n- **playwright**: Browser automation framework\n- **typescript**: Type safety and compilation\n- **tsx**: TypeScript execution in development\n\n## Browser Support\n\n### Supported Devices for Mobile Emulation\n\n- iPhone 12/13/14\n- iPad\n- Samsung Galaxy S21\n- Pixel 5\n\n### Supported Orientations\n\n- Portrait\n- Landscape\n\n## Security Considerations\n\n- Browser sessions run in headless mode\n- No persistent cookies or storage between sessions\n- Network requests can be intercepted and modified\n- JavaScript execution is sandboxed within the browser context\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Browser Installation**: Ensure Playwright browsers are installed with `npm run install-browsers`\n2. **Permission Errors**: Check file system permissions for screenshot and download paths\n3. **Network Issues**: Verify internet connectivity for navigation operations\n4. **Memory Usage**: Close unused sessions to free up resources\n\n### Debug Mode\n\nEnable debug logging by setting environment variables or modifying the server configuration.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nNon-Commercial License - see [LICENSE](LICENSE) file for details.\n\n**Important**: This software is free for personal, educational, and open source use. Commercial use is strictly prohibited without explicit permission from the author. For commercial licensing inquiries, please contact the author.\n\n## Support\n\nFor issues and questions, please open an issue on the [GitHub repository](https://github.com/badchars/mcp-browser/issues).\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Changelog\n\n### v0.3.0\n\n- **🔍 NEW**: Advanced API Endpoint Discovery\n  - AST-based JavaScript analysis with Babel parser\n  - Network call detection (fetch, axios, XMLHttpRequest, WebSocket)\n  - Metadata extraction (method, URL, headers, auth tokens, body schemas)\n  - Request spec generation (cURL, HTTPie, Postman examples)\n  - Context analysis with surrounding code examination\n  - Source map support for better code readability\n  - Dynamic endpoint validation in browser environment\n\n### v0.2.0\n\n- **🔍 NEW**: Advanced XSS Vulnerability Scanning\n  - Interactive XSS scanner with automatic PoC testing\n  - Comprehensive detection across scripts, attributes, URLs, and forms\n  - Real-time alert detection and vulnerability confirmation\n  - Detailed JSON reports with severity levels\n- **📁 NEW**: JavaScript Files Analysis \u0026 Fetching\n  - Complete JavaScript file downloading (external, inline, dynamic)\n  - Smart directory structure preservation from URLs\n  - Manifest generation with detailed metadata\n  - URL filtering and Performance API integration\n- **🔒 Enhanced**: Security-focused features and documentation\n- **📚 Improved**: Comprehensive usage examples and security use cases\n\n### v0.1.0\n\n- Initial release\n- Basic browser automation capabilities\n- XSS scanning functionality\n- Network request logging\n- Multi-browser support (Chromium, Firefox, WebKit)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbadchars%2Fmcp-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbadchars%2Fmcp-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbadchars%2Fmcp-browser/lists"}