Skip to content
Back to search

puppeteer-mcp-server

This MCP server provides browser automation capabilities through Puppeteer, allowing interaction with both new browser instances and existing Chrome windows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/merajmehrabi--puppeteer-mcp-server/badge.svg)](/listings/merajmehrabi--puppeteer-mcp-server)

HTML

<a href="/listings/merajmehrabi--puppeteer-mcp-server"><img src="/api/listings/merajmehrabi--puppeteer-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Install from npm

npm install -g puppeteer-mcp-server

You can also run it directly without installation using npx:

npx puppeteer-mcp-server

Option 2: Install from source

1. Clone this repository or download the source code 2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run the server:

npm start

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 325 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Puppeteer MCP Server
  2. [![smithery badge](https://smithery.ai/badge/@merajmehrabi/puppeteer-mcp-server)](https://smithery.ai/server/@merajmehrabi/puppeteer-mcp-server)
  3. This MCP server provides browser automation capabilities through Puppeteer, allowing interaction with both new browser instances and existing Chrome windows.
  4. ## Acknowledgment
  5. This 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.
  6. <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>
  7. ## Features
  8. - Navigate web pages
  9. - Take screenshots
  10. - Click elements
  11. - Fill forms
  12. - Select options
  13. - Hover elements
  14. - Execute JavaScript
  15. - Smart Chrome tab management:
  16. - Connect to active Chrome tabs
  17. - Preserve existing Chrome instances
  18. - Intelligent connection handling
  19. ## Project Structure
  20. ```
  21. /
  22. ├── src/
  23. │ ├── config/ # Configuration modules
  24. │ ├── tools/ # Tool definitions and handlers
  25. │ ├── browser/ # Browser connection management
  26. │ ├── types/ # TypeScript type definitions
  27. │ ├── resources/ # Resource handlers
  28. │ └── server.ts # Server initialization
  29. ├── index.ts # Entry point
  30. └── README.md # Documentation
  31. ```
  32. ## Installation
  33. ### Option 1: Install from npm
  34. ```bash
  35. npm install -g puppeteer-mcp-server
  36. ```
  37. You can also run it directly without installation using npx:
  38. ```bash
  39. npx puppeteer-mcp-server
  40. ```
  41. ### Option 2: Install from source
  42. 1. Clone this repository or download the source code
  43. 2. Install dependencies:
  44. ```bash
  45. npm install
  46. ```
  47. 3. Build the project:
  48. ```bash
  49. npm run build
  50. ```
  51. 4. Run the server:
  52. ```bash
  53. npm start
  54. ```
  55. ## MCP Server Configuration
  56. To use this tool with Claude, you need to add it to your MCP settings configuration file.
  57. ### For Claude Desktop App
  58. Add 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):
  59. #### If installed globally via npm:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "puppeteer": {
  64. "command": "puppeteer-mcp-server",
  65. "args": [],
  66. "env": {}
  67. }
  68. }
  69. }
  70. ```
  71. #### Using npx (without installation):
  72. ```json
  73. {
  74. "mcpServers": {
  75. "puppeteer": {
  76. "command": "npx",
  77. "args": ["-y", "puppeteer-mcp-server"],
  78. "env": {}
  79. }
  80. }
  81. }
  82. ```
  83. #### If installed from source:
  84. ```json
  85. {
  86. "mcpServers": {
  87. "puppeteer": {
  88. "command": "node",
  89. "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
  90. "env": {
  91. "NODE_OPTIONS": "--experimental-modules"
  92. }
  93. }
  94. }
  95. }
  96. ```
  97. ### For Claude VSCode Extension
  98. Add 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):
  99. #### If installed globally via npm:
  100. ```json
  101. {
  102. "mcpServers": {
  103. "puppeteer": {
  104. "command": "puppeteer-mcp-server",
  105. "args": [],
  106. "env": {}
  107. }
  108. }
  109. }
  110. ```
  111. #### Using npx (without installation):
  112. ```json
  113. {
  114. "mcpServers": {
  115. "puppeteer": {
  116. "command": "npx",
  117. "args": ["-y", "puppeteer-mcp-server"],
  118. "env": {}
  119. }
  120. }
  121. }
  122. ```
  123. #### If installed from source:
  124. ```json
  125. {
  126. "mcpServers": {
  127. "puppeteer": {
  128. "command": "node",
  129. "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
  130. "env": {
  131. "NODE_OPTIONS": "--experimental-modules"
  132. }
  133. }
  134. }
  135. }
  136. ```
  137. For source installation, replace `path/to/puppeteer-mcp-server` with the actual path to where you installed this tool.
  138. ## Usage
  139. ### Standard Mode
  140. The server will launch a new browser instance by default.
  141. ### Active Tab Mode
  142. To connect to an existing Chrome window:
  143. 1. Close any existing Chrome instances completely
  144. 2. Launch Chrome with remote debugging enabled:
  145. ```bash
  146. # Windows
  147. "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
  148. # macOS
  149. /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
  150. # Linux
  151. google-chrome --remote-debugging-port=9222
  152. ```
  153. 3. Navigate to your desired webpage in Chrome
  154. 4. Connect using the `puppeteer_connect_active_tab` tool:
  155. ```json
  156. {
  157. "targetUrl": "https://example.com", // Optional: specific tab URL
  158. "debugPort": 9222 // Optional: defaults to 9222
  159. }
  160. ```
  161. The server will:
  162. - Detect and connect to the Chrome instance running with remote debugging enabled
  163. - Preserve your Chrome instance (won't close it)
  164. - Find and connect to non-extension tabs
  165. - Provide clear error messages if connection fails
  166. ## Available Tools
  167. ### puppeteer_connect_active_tab
  168. Connect to an existing Chrome instance with remote debugging enabled.
  169. - Optional:
  170. - `targetUrl` - URL of the specific tab to connect to
  171. - `debugPort` - Chrome debugging port (default: 9222)
  172. ### puppeteer_navigate
  173. Navigate to a URL.
  174. - Required: `url` - The URL to navigate to
  175. ### puppeteer_screenshot
  176. Take a screenshot of the current page or a specific element.
  177. - Required: `name` - Name for the screenshot
  178. - Optional:
  179. - `selector` - CSS selector for element to screenshot
  180. - `width` - Width in pixels (default: 800)
  181. - `height` - Height in pixels (default: 600)
  182. ### puppeteer_click
  183. Click an element on the page.
  184. - Required: `selector` - CSS selector for element to click
  185. ### puppeteer_fill
  186. Fill out an input field.
  187. - Required:
  188. - `selector` - CSS selector for input field
  189. - `value` - Text to enter
  190. ### puppeteer_select
  191. Use dropdown menus.
  192. - Required:
  193. - `selector` - CSS selector for select element
  194. - `value` - Option value to select
  195. ### puppeteer_hover
  196. Hover over elements.
  197. - Required: `selector` - CSS selector for element to hover
  198. ### puppeteer_evaluate
  199. Execute JavaScript in the browser console.
  200. - Required: `script` - JavaScript code to execute
  201. ## Security Considerations
  202. When using remote debugging:
  203. - Only enable on trusted networks
  204. - Use a unique debugging port
  205. - Close debugging port when not in use
  206. - Never expose debugging port to public networks
  207. ## Logging and Debugging
  208. ### File-based Logging
  209. The server implements comprehensive logging using Winston:
  210. - Location: `logs/` directory
  211. - File Pattern: `mcp-puppeteer-YYYY-MM-DD.log`
  212. - Log Rotation:
  213. - Daily rotation
  214. - Maximum size: 20MB per file
  215. - Retention: 14 days
  216. - Automatic compression of old logs
  217. ### Log Levels
  218. - DEBUG: Detailed debugging information
  219. - INFO: General operational information
  220. - WARN: Warning messages
  221. - ERROR: Error events and exceptions
  222. ### Logged Information
  223. - Server startup/shutdown events
  224. - Browser operations (launch, connect, close)
  225. - Navigation attempts and results
  226. - Tool executions and outcomes
  227. - Error details with stack traces
  228. - Browser console output
  229. - Resource usage (screenshots, console logs)
  230. ## Error Handling
  231. The server provides detailed error messages for:
  232. - Connection failures
  233. - Missing elements
  234. - Invalid selectors
  235. - JavaScript execution errors
  236. - Screenshot failures
  237. Each tool call returns:
  238. - Success/failure status
  239. - Detailed error message if failed
  240. - Operation result data if successful
  241. All errors are also logged to the log files with:
  242. - Timestamp
  243. - Error message
  244. - Stack trace (when available)
  245. - Context information
  246. ## Contributing
  247. Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and contribute to the project.
  248. ## License
  249. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.