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., "@Playwright Debug MCP Server analyze trace at ./test-results/trace.zip"
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.
An MCP (Model Context Protocol) server designed to supercharge AI-assisted debugging of Playwright tests.
Instead of manually downloading and scrubbing through trace.zip files to find why a test failed, simply point this MCP server to your trace file or Playwright results directory. The server instantly parses the exact failing action, action history, network failures, DOM snapshots, and screenshots so your AI assistant (like Claude, Cursor, Cline, or Antigravity) can instantly pinpoint the failure and suggest a code fix.
🐛 analyze_trace: Automatically extracts the exact action that hung or failed, the selector used, DOM snapshots, and Base64 screenshots.
📜 get_action_history: Extracts a full chronological timeline of every user action performed during the test.
🌐 get_network_log: Filters network requests inside the trace to find exactly what APIs returned 4xx or 5xx right before the crash.
🖼️ get_screenshots_around_time: Visual timeline extraction tool for the AI to view the exact state of the browser before and after any given timestamp.
🛠️ suggest_fix: A built-in logic engine mapping common Playwright errors to actionable fixes.
Related MCP server: LocatorLabs MCP Server
Debugging failed E2E tests often involves tedious, manual steps: downloading the trace artifact from CI, opening it locally via playwright show-trace, and manually scrubbing through a timeline to see what happened. By the time you figure out the issue, valuable time has been wasted.
This MCP bridges the gap between raw test output and AI problem-solving. By giving your AI direct programmatic access to Playwright's trace files, the AI can instantly inspect the DOM, network requests, screenshots, and action history. Instead of guessing why a test failed based on a stack trace, your AI assistant can actually "see" the exact browser state at the moment of failure.
CI/CD Pipeline Debugging: Quickly understand why a test failed in the CI environment without downloading heavy artifacts. Just provide the path to the trace file to your AI assistant.
Tackling Flaky Tests: The AI can analyze action history and network logs to identify race conditions or missing wait states that cause intermittent failures.
Local Test Authoring & Fixing: When writing tests locally, easily feed trace results to Cursor, Claude, or Cline to get an instant, contextual fix (e.g., "Ah, the button was obscured by a modal, use force: true or wait for the modal to close").
Learning & Onboarding: Helps junior QA engineers and developers learn Playwright best practices through AI-guided analysis and fix suggestions.
Massive Time Savings: Eliminate the 5-10 minutes usually spent manually downloading, extracting, and loading trace files for every single test failure.
Reduced Context Switching: Debug tests directly within your IDE using your preferred AI assistant instead of constantly switching between your editor, terminal, and browser trace viewer.
Actionable Insights: It doesn't just surface errors; the built-in suggest_fix logic provides concrete code suggestions to resolve common Playwright pitfalls (like strict mode violations or detached DOM elements).
Boosted Developer Velocity: Automated extraction of DOM snapshots and screenshots allows teams to fix broken tests immediately, keeping the build green and deploying faster.
This server can be used out-of-the-box by any MCP-compatible AI agent without needing to clone or configure anything locally.
Go to Cursor Settings > Features > MCP Servers
Click + Add New MCP Server
Set Type to command
Set Name to playwright-debug
Set Command to:
npx -y github:aakarshitsharma06/playwright-debug-mcpOpen your MCP configuration file (usually in ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json) and add:
{
"mcpServers": {
"playwright-debugger": {
"command": "npx",
"args": ["-y", "github:aakarshitsharma06/playwright-debug-mcp"]
}
}
}Open your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json) and add:
{
"mcpServers": {
"playwright-debugger": {
"command": "npx",
"args": ["-y", "github:aakarshitsharma06/playwright-debug-mcp"]
}
}
}If you want to modify or run the code locally:
npm install
npm run build
node dist/index.jsAnalyze a Playwright trace.zip file for a failed test
| Name | Required | Description | Default |
|---|---|---|---|
| trace_path | Yes | Absolute path to trace.zip file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the purpose without detailing output, side effects, or permissions. The description does not reveal what the analysis produces or any constraints.
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, but could be more structured by front-loading key terms. It is efficient with no wasted words.
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 one parameter, no output schema, and no annotations, the description is insufficient. It does not explain what the analysis entails, what the output looks like, or any behavioral details, leaving significant gaps for correct tool invocation.
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 parameter 'trace_path' is fully described in the schema with coverage 100%. The description adds contextual purpose but no additional parameter meaning beyond the schema.
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 verb 'Analyze', the resource 'Playwright trace.zip file', and the context 'for a failed test'. It distinguishes from siblings like get_action_history or get_failed_tests by specifying trace analysis.
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 vs alternatives, nor prerequisites such as requiring a trace from a failed test. The description provides no exclusions or context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chronological list of all actions performed in a Playwright trace
| Name | Required | Description | Default |
|---|---|---|---|
| trace_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits (e.g., read-only, destructive, auth needs). It only states the output, omitting any such details.
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, clear sentence with no redundancy, perfectly concise.
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, the description omits essential details like return format, action types, or filtering capabilities, leaving the agent underinformed.
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 0% and the description does not explain the trace_path parameter's format or meaning, providing no value beyond the schema's type field.
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 retrieves a chronological list of actions from a Playwright trace, effectively distinguishing it from sibling tools that handle network logs, screenshots, or failed tests.
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 the tool is for getting action history, but provides no explicit guidance on when to use versus alternatives like analyze_trace or get_failed_tests, or any conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get failed tests from a Playwright JSON report
| Name | Required | Description | Default |
|---|---|---|---|
| report_path | Yes | Absolute path to Playwright JSON report file e.g. /project/test-results/results.json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavioral traits. It only states that the tool retrieves failed tests, implying a read operation, but does not mention side effects, permissions, rate limits, or output structure. Minimal behavioral context is provided.
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. It is front-loaded with the action and resource, achieving high efficiency.
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 (one parameter, no output schema), the description is adequate but lacks information about the return format or structure. With no output schema, additional details on what the agent can expect would improve completeness. It meets the minimum threshold but leaves gaps.
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% for the single parameter report_path, which already includes a clear description (e.g., file path and example). The tool description adds no additional meaning beyond the schema, so baseline 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 clearly states the verb 'Get' and the resource 'failed tests from a Playwright JSON report', making the tool's purpose understandable. It distinguishes from siblings implicitly as the sibling tools have different functions (e.g., analyze_trace, get_network_log), but it does not explicitly differentiate.
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. It does not mention prerequisites, context, or when not to use it. The sibling tools suggest alternatives for debugging, but no explicit comparison is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get network logs from a Playwright trace.zip file
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | all | |
| trace_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does not disclose any behavioral traits (e.g., read-only nature, error conditions, or side effects), leaving the agent uninformed.
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 very short (one sentence), but it is not effective conciseness as it sacrifices necessary detail; it could be expanded to include parameter hints or output info.
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 lack of output schema and annotations, the description should explain what logs are returned and any limitations; it does not, making the tool incomplete 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?
The schema has 0% description coverage, and the tool description adds no meaning to parameters—'trace_path' and 'filter' are unexplained (e.g., path format, filter 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 clearly states the verb 'get' and the resource 'network logs from a Playwright trace.zip file', distinguishing it from sibling tools like analyze_trace or get_action_history.
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 (e.g., analyze_trace for broader analysis), nor are any prerequisites or context given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get screenshots immediately before and after a specific timestamp in the trace
| Name | Required | Description | Default |
|---|---|---|---|
| trace_path | Yes | ||
| target_time | Yes | The timeline timestamp (in ms) of the action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'immediately before and after' but does not specify what 'immediately' means (e.g., count of screenshots, relation to adjacent actions) or disclose any behavioral traits like permissions or side effects.
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, front-loaded sentence with no wasted words. It could benefit from additional detail, but it is concise.
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, no annotations, and an incomplete parameter description, the description does not sufficiently explain the tool's behavior (e.g., number of screenshots, prerequisites). It leaves important questions unanswered.
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 50% (only target_time has a description). The tool description does not add meaning beyond the schema; it merely echoes 'timestamp'. It fails to clarify the purpose of trace_path or provide 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 clearly states the verb 'Get' and the resource 'screenshots' along with a specific context ('immediately before and after a specific timestamp'). It distinguishes from sibling tools like get_action_history and get_network_log.
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 usage when needing screenshots around a timestamp but does not explicitly state when to use this tool versus alternatives or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest a fix for a Playwright test error
| Name | Required | Description | Default |
|---|---|---|---|
| error_message | Yes | ||
| selector_used | No | ||
| failing_action | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only states that a fix is suggested, but does not disclose whether the tool is read-only, requires permissions, or what the output format is.
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 short sentence, but it is under-specified. While concise, it lacks necessary detail, making it insufficiently informative.
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?
Despite low complexity (3 parameters, no output schema), the description is incomplete. It does not explain what the tool returns or how the suggestion is presented, leaving gaps for the 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 0%, yet the description adds no information about the three parameters (error_message, selector_used, failing_action). The description fails to compensate for the missing schema descriptions.
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 verb 'Suggest', the resource 'a fix', and the context 'Playwright test error', making the tool's purpose specific and distinguishable from sibling tools like analyze_trace or get_failed_tests.
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. The description does not specify scenarios, prerequisites, or when not to use it.
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.
v1.0.0analyze_traceget_action_historyget_failed_testsget_network_logget_screenshots_around_timesuggest_fixEach tool targets a distinct aspect of Playwright debugging: trace analysis, action history, failed tests, network logs, screenshots, and fix suggestions. No two tools have overlapping purposes.
Most tools follow a 'get_' prefix pattern, but 'analyze_trace' and 'suggest_fix' deviate. The naming is largely consistent and readable.
With 6 tools, the server is well-scoped for its debugging purpose—enough to cover key workflows without excess.
Covers core debugging operations on traces and reports. A minor gap is the lack of a tool for replaying traces or getting test logs, but the set is complete for common debugging tasks.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Agentic testing: HyperExecute jobs, test failure triage, SmartUI visual diffs, a11y audits
AI QA tester — real browsers scan sites for bugs, SEO, perf, and accessibility issues via chat.
Playwright selector risk checks with healing suggestions and receipts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/aakarshitsharma06/playwright-debug-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
