{"_id":"@mseep/puppeteer-mcp-server","name":"@mseep/puppeteer-mcp-server","dist-tags":{"latest":"0.7.2"},"versions":{"0.7.2":{"name":"@mseep/puppeteer-mcp-server","version":"0.7.2","description":"Experimental MCP server for browser automation using Puppeteer (inspired by @modelcontextprotocol/server-puppeteer)","license":"MIT","author":{"name":"Meraj Mehrabi"},"homepage":"https://github.com/merajmehrabi/puppeteer-mcp-server","bugs":{"url":"https://github.com/merajmehrabi/puppeteer-mcp-server/issues"},"repository":{"type":"git","url":"git+https://github.com/merajmehrabi/puppeteer-mcp-server.git"},"type":"module","bin":{"mcp-server-puppeteer":"dist/index.js"},"scripts":{"build":"tsc && shx chmod +x dist/*.js","prepare":"npm run build","watch":"tsc --watch"},"dependencies":{"@modelcontextprotocol/sdk":"1.0.1","puppeteer":"^23.4.0","winston":"^3.11.0","winston-daily-rotate-file":"^5.0.0"},"devDependencies":{"@types/node":"^20.11.17","@types/winston":"^2.4.4","shx":"^0.3.4","typescript":"^5.6.2"},"keywords":["mseep","mcp-server"],"publisher":"mseep","_id":"@mseep/puppeteer-mcp-server@0.7.2","gitHead":"41d656953cba033d6d993ccca589be72c2e1db3f","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-zZIuhPvVlyx1PbM3kacxRb9uxpaVBBEcBYmgjyTzmSXwXpmYobKycnon08p+QgWDNRbBaPhe4fDlqqByR/gtjA==","shasum":"c05009b06382f096e1f4e911dbf5015a091791be","tarball":"https://registry.npmjs.org/@mseep/puppeteer-mcp-server/-/puppeteer-mcp-server-0.7.2.tgz","fileCount":21,"unpackedSize":41681,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCBJAL0/PFeb8eVZo95nyRb0gxKUHhQtI+ehRmS+bGWVwIhAIfERxLbAVO5x9qxMknWZBU+aYpK4bYnfYHpGTvMNaaq"}]},"_npmUser":{"name":"skydeckai","email":"support@skydeck.ai"},"directories":{},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/puppeteer-mcp-server_0.7.2_1744779355157_0.08577727112507239"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-16T04:55:55.090Z","0.7.2":"2025-04-16T04:55:55.361Z","modified":"2025-04-16T04:55:55.629Z"},"maintainers":[{"name":"skydeckai","email":"support@skydeck.ai"}],"description":"Experimental MCP server for browser automation using Puppeteer (inspired by @modelcontextprotocol/server-puppeteer)","homepage":"https://github.com/merajmehrabi/puppeteer-mcp-server","keywords":["mseep","mcp-server"],"repository":{"type":"git","url":"git+https://github.com/merajmehrabi/puppeteer-mcp-server.git"},"author":{"name":"Meraj Mehrabi"},"bugs":{"url":"https://github.com/merajmehrabi/puppeteer-mcp-server/issues"},"license":"MIT","readme":"# Puppeteer MCP Server\n\n[![smithery badge](https://smithery.ai/badge/@merajmehrabi/puppeteer-mcp-server)](https://smithery.ai/server/@merajmehrabi/puppeteer-mcp-server)\nThis MCP server provides browser automation capabilities through Puppeteer, allowing interaction with both new browser instances and existing Chrome windows.\n\n## Acknowledgment\n\nThis project is an experimental implementation inspired by [@modelcontextprotocol/server-puppeteer](https://github.com/modelcontextprotocol/servers). While it shares similar goals and concepts, it explores alternative approaches to browser automation through the Model Context Protocol.\n\n<a href=\"https://glama.ai/mcp/servers/lpt1tvbubf\"><img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/lpt1tvbubf/badge\" alt=\"Puppeteer Server MCP server\" /></a>\n\n## Features\n\n- Navigate web pages\n- Take screenshots\n- Click elements\n- Fill forms\n- Select options\n- Hover elements\n- Execute JavaScript\n- Smart Chrome tab management:\n  - Connect to active Chrome tabs\n  - Preserve existing Chrome instances\n  - Intelligent connection handling\n\n## Project Structure\n\n```\n/\n├── src/\n│   ├── config/        # Configuration modules\n│   ├── tools/         # Tool definitions and handlers\n│   ├── browser/       # Browser connection management\n│   ├── types/         # TypeScript type definitions\n│   ├── resources/     # Resource handlers\n│   └── server.ts      # Server initialization\n├── index.ts          # Entry point\n└── README.md        # Documentation\n```\n\n## Installation\n\n### Option 1: Install from npm\n\n```bash\nnpm install -g puppeteer-mcp-server\n```\n\nYou can also run it directly without installation using npx:\n\n```bash\nnpx puppeteer-mcp-server\n```\n\n### Option 2: Install from source\n\n1. Clone this repository or download the source code\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Build the project:\n\n```bash\nnpm run build\n```\n\n4. Run the server:\n\n```bash\nnpm start\n```\n\n## MCP Server Configuration\n\nTo use this tool with Claude, you need to add it to your MCP settings configuration file.\n\n### For Claude Desktop App\n\nAdd the following to your Claude Desktop configuration file (located at `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n#### If installed globally via npm:\n\n```json\n{\n  \"mcpServers\": {\n    \"puppeteer\": {\n      \"command\": \"puppeteer-mcp-server\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### Using npx (without installation):\n\n```json\n{\n  \"mcpServers\": {\n    \"puppeteer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"puppeteer-mcp-server\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### If installed from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"puppeteer\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/puppeteer-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"NODE_OPTIONS\": \"--experimental-modules\"\n      }\n    }\n  }\n}\n```\n\n### For Claude VSCode Extension\n\nAdd the following to your Claude VSCode extension MCP settings file (located at `%APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json` on Windows or `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` on macOS):\n\n#### If installed globally via npm:\n\n```json\n{\n  \"mcpServers\": {\n    \"puppeteer\": {\n      \"command\": \"puppeteer-mcp-server\",\n      \"args\": [],\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### Using npx (without installation):\n\n```json\n{\n  \"mcpServers\": {\n    \"puppeteer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"puppeteer-mcp-server\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n#### If installed from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"puppeteer\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/puppeteer-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"NODE_OPTIONS\": \"--experimental-modules\"\n      }\n    }\n  }\n}\n```\n\nFor source installation, replace `path/to/puppeteer-mcp-server` with the actual path to where you installed this tool.\n\n## Usage\n\n### Standard Mode\n\nThe server will launch a new browser instance by default.\n\n### Active Tab Mode\n\nTo connect to an existing Chrome window:\n\n1. Close any existing Chrome instances completely\n\n2. Launch Chrome with remote debugging enabled:\n   ```bash\n   # Windows\n   \"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe\" --remote-debugging-port=9222\n\n   # macOS\n   /Applications/Google\\ Chrome.app/Contents/MacOS/Google\\ Chrome --remote-debugging-port=9222\n\n   # Linux\n   google-chrome --remote-debugging-port=9222\n   ```\n\n3. Navigate to your desired webpage in Chrome\n\n4. Connect using the `puppeteer_connect_active_tab` tool:\n   ```json\n   {\n     \"targetUrl\": \"https://example.com\", // Optional: specific tab URL\n     \"debugPort\": 9222 // Optional: defaults to 9222\n   }\n   ```\n\nThe server will:\n- Detect and connect to the Chrome instance running with remote debugging enabled\n- Preserve your Chrome instance (won't close it)\n- Find and connect to non-extension tabs\n- Provide clear error messages if connection fails\n\n## Available Tools\n\n### puppeteer_connect_active_tab\nConnect to an existing Chrome instance with remote debugging enabled.\n- Optional:\n  - `targetUrl` - URL of the specific tab to connect to\n  - `debugPort` - Chrome debugging port (default: 9222)\n\n### puppeteer_navigate\nNavigate to a URL.\n- Required: `url` - The URL to navigate to\n\n### puppeteer_screenshot\nTake a screenshot of the current page or a specific element.\n- Required: `name` - Name for the screenshot\n- Optional:\n  - `selector` - CSS selector for element to screenshot\n  - `width` - Width in pixels (default: 800)\n  - `height` - Height in pixels (default: 600)\n\n### puppeteer_click\nClick an element on the page.\n- Required: `selector` - CSS selector for element to click\n\n### puppeteer_fill\nFill out an input field.\n- Required:\n  - `selector` - CSS selector for input field\n  - `value` - Text to enter\n\n### puppeteer_select\nUse dropdown menus.\n- Required:\n  - `selector` - CSS selector for select element\n  - `value` - Option value to select\n\n### puppeteer_hover\nHover over elements.\n- Required: `selector` - CSS selector for element to hover\n\n### puppeteer_evaluate\nExecute JavaScript in the browser console.\n- Required: `script` - JavaScript code to execute\n\n## Security Considerations\n\nWhen using remote debugging:\n- Only enable on trusted networks\n- Use a unique debugging port\n- Close debugging port when not in use\n- Never expose debugging port to public networks\n\n## Logging and Debugging\n\n### File-based Logging\nThe server implements comprehensive logging using Winston:\n\n- Location: `logs/` directory\n- File Pattern: `mcp-puppeteer-YYYY-MM-DD.log`\n- Log Rotation:\n  - Daily rotation\n  - Maximum size: 20MB per file\n  - Retention: 14 days\n  - Automatic compression of old logs\n\n### Log Levels\n- DEBUG: Detailed debugging information\n- INFO: General operational information\n- WARN: Warning messages\n- ERROR: Error events and exceptions\n\n### Logged Information\n- Server startup/shutdown events\n- Browser operations (launch, connect, close)\n- Navigation attempts and results\n- Tool executions and outcomes\n- Error details with stack traces\n- Browser console output\n- Resource usage (screenshots, console logs)\n\n## Error Handling\n\nThe server provides detailed error messages for:\n- Connection failures\n- Missing elements\n- Invalid selectors\n- JavaScript execution errors\n- Screenshot failures\n\nEach tool call returns:\n- Success/failure status\n- Detailed error message if failed\n- Operation result data if successful\n\nAll errors are also logged to the log files with:\n- Timestamp\n- Error message\n- Stack trace (when available)\n- Context information\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and contribute to the project.\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","readmeFilename":"README.md","_rev":"1-82ac3325cac3df34c4fb60e0cdd47403"}