The Puppeteer MCP Server provides browser automation capabilities through Puppeteer, allowing you to:
Connect to existing Chrome: Connect to active Chrome instances with remote debugging enabled
Navigate web pages: Automate browser navigation to specific URLs
Capture screenshots: Take screenshots of entire pages or specific elements
Interact with elements: Click, fill input fields, select dropdown options, and hover over elements
Execute JavaScript: Run custom JavaScript code in the browser console
Manage connections: Intelligently handle Chrome tab connections while preserving the browser instance
Detailed logging: Access comprehensive logging and error handling for all operations
The server offers configuration flexibility and can be used globally via npm, through npx, or installed from source.
This is a MCP server implementation that provides browser automation capabilities through Puppeteer, enabling various web interactions including navigation, screenshots, clicking elements, filling forms, and executing JavaScript in browser contexts.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Puppeteer MCP Server take a screenshot of the homepage and save it as screenshot.png"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This MCP server provides browser automation capabilities through Puppeteer, allowing interaction with both new browser instances and existing Chrome windows.
This project is an experimental implementation inspired by @modelcontextprotocol/server-puppeteer. While it shares similar goals and concepts, it explores alternative approaches to browser automation through the Model Context Protocol.
Related MCP server: Puppeteer MCP Server
Navigate web pages
Take screenshots
Click elements
Fill forms
Select options
Hover elements
Execute JavaScript
Smart Chrome tab management:
Connect to active Chrome tabs
Preserve existing Chrome instances
Intelligent connection handling
/
├── src/
│ ├── config/ # Configuration modules
│ ├── tools/ # Tool definitions and handlers
│ ├── browser/ # Browser connection management
│ ├── types/ # TypeScript type definitions
│ ├── resources/ # Resource handlers
│ └── server.ts # Server initialization
├── index.ts # Entry point
└── README.md # Documentationnpm install -g puppeteer-mcp-serverYou can also run it directly without installation using npx:
npx puppeteer-mcp-serverClone this repository or download the source code
Install dependencies:
npm installBuild the project:
npm run buildRun the server:
npm startTo use this tool with Claude, you need to add it to your MCP settings configuration file.
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):
{
"mcpServers": {
"puppeteer": {
"command": "puppeteer-mcp-server",
"args": [],
"env": {}
}
}
}{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "puppeteer-mcp-server"],
"env": {}
}
}
}{
"mcpServers": {
"puppeteer": {
"command": "node",
"args": ["path/to/puppeteer-mcp-server/dist/index.js"],
"env": {
"NODE_OPTIONS": "--experimental-modules"
}
}
}
}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):
{
"mcpServers": {
"puppeteer": {
"command": "puppeteer-mcp-server",
"args": [],
"env": {}
}
}
}{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "puppeteer-mcp-server"],
"env": {}
}
}
}{
"mcpServers": {
"puppeteer": {
"command": "node",
"args": ["path/to/puppeteer-mcp-server/dist/index.js"],
"env": {
"NODE_OPTIONS": "--experimental-modules"
}
}
}
}For source installation, replace path/to/puppeteer-mcp-server with the actual path to where you installed this tool.
The server will launch a new browser instance by default.
To connect to an existing Chrome window:
Close any existing Chrome instances completely
Launch Chrome with remote debugging enabled:
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222Navigate to your desired webpage in Chrome
Connect using the puppeteer_connect_active_tab tool:
{
"targetUrl": "https://example.com", // Optional: specific tab URL
"debugPort": 9222 // Optional: defaults to 9222
}The server will:
Detect and connect to the Chrome instance running with remote debugging enabled
Preserve your Chrome instance (won't close it)
Find and connect to non-extension tabs
Provide clear error messages if connection fails
Connect to an existing Chrome instance with remote debugging enabled.
Optional:
targetUrl - URL of the specific tab to connect to
debugPort - Chrome debugging port (default: 9222)
Navigate to a URL.
Required: url - The URL to navigate to
Take a screenshot of the current page or a specific element.
Required: name - Name for the screenshot
Optional:
selector - CSS selector for element to screenshot
width - Width in pixels (default: 800)
height - Height in pixels (default: 600)
Click an element on the page.
Required: selector - CSS selector for element to click
Fill out an input field.
Required:
selector - CSS selector for input field
value - Text to enter
Use dropdown menus.
Required:
selector - CSS selector for select element
value - Option value to select
Hover over elements.
Required: selector - CSS selector for element to hover
Execute JavaScript in the browser console.
Required: script - JavaScript code to execute
When using remote debugging:
Only enable on trusted networks
Use a unique debugging port
Close debugging port when not in use
Never expose debugging port to public networks
The server implements comprehensive logging using Winston:
Location: logs/ directory
File Pattern: mcp-puppeteer-YYYY-MM-DD.log
Log Rotation:
Daily rotation
Maximum size: 20MB per file
Retention: 14 days
Automatic compression of old logs
DEBUG: Detailed debugging information
INFO: General operational information
WARN: Warning messages
ERROR: Error events and exceptions
Server startup/shutdown events
Browser operations (launch, connect, close)
Navigation attempts and results
Tool executions and outcomes
Error details with stack traces
Browser console output
Resource usage (screenshots, console logs)
The server provides detailed error messages for:
Connection failures
Missing elements
Invalid selectors
JavaScript execution errors
Screenshot failures
Each tool call returns:
Success/failure status
Detailed error message if failed
Operation result data if successful
All errors are also logged to the log files with:
Timestamp
Error message
Stack trace (when available)
Context information
Contributions are welcome! Please read our Contributing Guidelines for details on how to submit pull requests, report issues, and contribute to the project.
This project is licensed under the MIT License - see the LICENSE file for details.
Click an element on the page
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector for element to click |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose behavior such as whether it waits for element, clicks on the first match, or handles page navigation. This is critical for a click action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, zero waste. Front-loaded with the verb and resource. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 param, no output schema), the description is minimally adequate but lacks behavioral details such as what happens on success/failure, or if it triggers navigation. Could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'selector' is fully described in the schema as 'CSS selector for element to click' (100% coverage). The description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Click an element on the page' clearly states the action (click) and the target (element on page). It distinguishes itself from sibling tools like puppeteer_hover or puppeteer_fill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, when-not-to-use, or context (e.g., element must be visible/interactable).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to an existing Chrome instance with remote debugging enabled
| Name | Required | Description | Default |
|---|---|---|---|
| targetUrl | No | Optional URL of the target tab to connect to. If not provided, connects to the first available tab. | |
| debugPort | No | Optional Chrome debugging port (default: 9222) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral transparency. It fails to disclose side effects (e.g., potential connection failures, state changes like setting a current tab), error conditions, or prerequisites. The description is too sparse given the tool's role in establishing a connection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is well-structured and front-loaded, immediately conveying the action and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's importance (establishing a connection before other operations), the description is incomplete. It does not explain the connection lifecycle, that this tool is a prerequisite for sibling tools, or what the return value (if any) indicates. The lack of an output schema increases the need for description completeness, which is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add any additional meaning beyond the schema; it merely restates the purpose without elaborating on parameter usage, such as how to construct the targetUrl or what debugging port implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: connecting to an existing Chrome instance with remote debugging. It specifies the verb 'connect' and the resource 'Chrome instance', which distinguishes it from sibling tools that perform actions on a connected page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the Chrome instance must already have remote debugging enabled, but it does not explicitly state when to use this tool versus alternatives, such as launching a new browser. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute JavaScript in the browser console
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes | JavaScript code to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral transparency. It only says 'Execute JavaScript in the browser console' without disclosing that the code runs in the page context, can modify the DOM, trigger network requests, or return values. Critical safety and side-effect information is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that clearly states the core function without any extraneous words. While it is brief, every word is purposeful, making it efficient for an AI agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the input schema (one parameter) and the lack of output schema, the description should clarify return values, execution context, and error behavior. It fails to do so, leaving the agent without crucial information for safely using this powerful tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'script', so the baseline is 3. The description adds no further meaning beyond the schema, as it merely restates the tool's action without elaborating on the parameter's usage or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Execute') and clearly identifies the resource ('JavaScript in the browser console'). It effectively distinguishes this tool from siblings like puppeteer_click or puppeteer_navigate, which perform different browser actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives or when to avoid it. It does not mention scenarios such as debugging, extracting data, or testing, nor does it warn about potential risks of executing arbitrary code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fill out an input field
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector for input field | |
| value | Yes | Value to fill |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details such as whether the field is cleared before filling, what events are triggered (e.g., input, change), or error handling (e.g., what happens if the selector is not found). With no annotations, the description fails to provide necessary behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. However, it could be slightly longer to include usage context without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fill tool with a complete input schema, the description is adequate. However, it does not explain return values or side effects, which would be helpful given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions. It merely restates the tool's purpose without elaborating on how the parameters affect behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Fill out an input field' clearly states the verb (Fill) and resource (input field). It distinguishes from sibling tools like puppeteer_click, puppeteer_select, and puppeteer_navigate, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, it does not clarify when to use fill versus puppeteer_select for dropdowns or puppeteer_click for buttons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hover an element on the page
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector for element to hover |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It does not disclose whether hover triggers events, waits for visibility, or fails gracefully—critical for a browser automation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste, but extreme brevity sacrifices necessary detail. Frontier for a tool with this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should cover behavior like error handling, scrolling into view, or event triggering. It does not, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description 'CSS selector for element to hover' adds no meaning beyond the schema; it only restates the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Hover an element on the page' uses a specific verb ('hover') and resource ('element on the page'), clearly distinguishing it from sibling tools like puppeteer_click or puppeteer_fill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use hover versus alternatives like click or fill. The agent must infer use cases from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take a screenshot of the current page or a specific element
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the screenshot | |
| selector | No | CSS selector for element to screenshot | |
| width | No | Width in pixels (default: 800) | |
| height | No | Height in pixels (default: 600) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the basic action. Does not disclose behavioral details such as waiting for elements, scrolling, error handling, or whether it captures the full page or viewport.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that adequately conveys the core functionality. Concise, but could benefit from slightly more detail to improve completeness without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters and no output schema, the description is too minimal. Fails to explain default behavior, interaction between parameters (e.g., selector vs full page), or return format, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with descriptions for all 4 parameters. The description does not add additional context beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Take a screenshot' and the resource 'current page or a specific element'. Easily distinguishes from sibling tools like puppeteer_click or puppeteer_navigate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for capturing page or element screenshots, but no explicit guidance on when to use this over alternatives like puppeteer_evaluate for content extraction or other puppeteer tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select an element on the page with Select tag
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector for element to select | |
| value | Yes | Value to select |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The description only says 'Select an element', which is tautological. It does not disclose that the tool selects an option in a dropdown, that it triggers change events, or how it behaves with multiple selects. Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. It is not front-loaded with the most critical information (e.g., that it selects an option from a <select>). The brevity leaves gaps in understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description should still explain the expected behavior (e.g., selecting an option, triggering events). No output schema exists, so the description should cover return values. It fails to provide enough context for an AI agent to invoke it correctly without confusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both 'selector' and 'value'. The tool description adds no extra meaning beyond the schema. Baseline is 3, and the description does not compensate with additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Select an element on the page with Select tag', which indicates the tool interacts with a <select> element, but it is not explicitly clear that it selects an option from a dropdown. The verb and resource are present but vague. Sibling tools like puppeteer_fill suggest this is a distinct action, but the description lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool vs. alternatives (e.g., puppeteer_fill for text inputs, puppeteer_click for buttons). It fails to mention that it is specifically for <select> elements or that it changes the selected option.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
puppeteer_clickpuppeteer_connect_active_tabpuppeteer_evaluatepuppeteer_fillpuppeteer_hoverpuppeteer_navigatepuppeteer_screenshotpuppeteer_selectEach tool targets a distinct browser action (click, navigate, fill, hover, etc.) with no overlap, making selection unambiguous.
All tools follow a consistent pattern: 'puppeteer_' prefix followed by a clear action verb, ensuring predictability.
With 8 tools covering essential browser interactions, the count is well-scoped for a focused automation server.
Core operations are covered, but missing explicit waiting or content extraction tools; however, puppeteer_evaluate can compensate.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/merajmehrabi/puppeteer-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
