The VibeCheck MCP server allows AI assistants to record browser sessions as shareable bug reports and analyze existing VibeCheck tracks.
Record Browser Sessions
AI agents drive a real browser (via browser_navigate, browser_click, browser_type, browser_finish) to perform tasks.
Records video, console logs, network requests (with response bodies), and a labeled action timeline — all synced.
Supports local dev environments and VPNs; automatically condenses video by cutting idle time if ffmpeg is available.
Requires a VibeCheck API key.
Analyze Bug Reports (no API key required)
get_track – Fetch a full bug report including console logs, network requests, user actions, web vitals, and optional screenshot. Supports filtering which sections to include.
analyze_track_errors – Focused view of console errors with stack traces and failed network requests with response bodies.
get_track_network – Deep-dive into network activity: detect failed (4xx/5xx) and slow requests (configurable threshold), filter by status, and get a full summary table.
get_track_performance – Review web vitals with ratings, navigation timing per page, and optimization suggestions.
get_track_actions – Chronological user interaction timeline, auto-generated steps to reproduce, and action type breakdown (click, input, scroll, navigation, etc.).
Allows Windsurf (powered by Codeium) to record browser sessions and analyze VibeCheck bug reports, providing tools for browser automation and bug report analysis.
Click on "Deploy 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., "@VibeCheck MCP analyze errors from track https://vibecheck-qa.com/track/abc123"
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.
MCP server for VibeCheck — connect AI assistants (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code) to your bug reports, and let them record their own browser sessions as shareable bug reports.
📖 Full guide — features, installation, use cases → DOCS.md
Give your AI agent a task in plain English — it drives a real browser on your machine while VibeCheck records everything, then returns a shareable link:
You: Go to staging.myapp.com/cart, add a product and check the total
updates. Record it and send me the link.
Agent: ⏺ Opening browser — recording started
⏺ Clicked: Add to cart
⏺ Validated: total updated to $42.00 ✓
Recording uploaded to VibeCheck.
Shareable link: https://app.vibecheck-qa.com/tracks/1783…The link opens a full bug report: video of the session, console logs, network requests (with response bodies), and a labeled action timeline — all synced. Anyone can watch it, no account needed.
No AI inside — your assistant does the reasoning and clicking; this server is a recorded browser plus an uploader. No extra LLM costs.
Local browser — works against localhost dev servers and VPN-only staging. Uses your installed Chrome/Edge automatically (fresh isolated profile); auto-downloads a browser if neither exists.
11 tools — browser_navigate, browser_snapshot, browser_click, browser_type, browser_press_key, browser_select_option, browser_hover, browser_scroll, browser_screenshot, browser_wait_for, browser_finish (uploads + returns the link).
Perfect for: "go validate this page", reproducing a bug from an existing report, proving a fix before a PR, smoke-testing a deploy.
Related MCP server: TracePulse
Node.js 18+
A browser — nothing to install if you have Google Chrome or Microsoft Edge (auto-detected). Otherwise one is auto-downloaded on first run (or pre-download: npx playwright install chromium)
A VibeCheck API key (recording only — the read tools below need no key):
Sign in at app.vibecheck-qa.com
Open the API Keys page (app.vibecheck-qa.com/api-keys) → Generate key
The dialog gives you a ready-made setup: a copy-paste Claude Code command with your key already inside, plus one-click Add to Cursor / Add to VS Code buttons — use those and skip the manual configs below
claude mcp add vibecheck \
-e VIBECHECK_API_KEY=vck_your_key_here \
-- npx -y @vibecheck-mcp/mcpAdd to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude Desktop:
{
"mcpServers": {
"vibecheck": {
"command": "npx",
"args": ["-y", "@vibecheck-mcp/mcp"],
"env": { "VIBECHECK_API_KEY": "vck_your_key_here" }
}
}
}Add the same block to .cursor/mcp.json (or use the one-click Add to Cursor button on VibeCheck's API Keys page):
{
"mcpServers": {
"vibecheck": {
"command": "npx",
"args": ["-y", "@vibecheck-mcp/mcp"],
"env": { "VIBECHECK_API_KEY": "vck_your_key_here" }
}
}
}Add the same mcpServers block to ~/.codeium/windsurf/mcp_config.json.
Add to .vscode/mcp.json (note the key is servers):
{
"servers": {
"vibecheck": {
"command": "npx",
"args": ["-y", "@vibecheck-mcp/mcp"],
"env": { "VIBECHECK_API_KEY": "vck_your_key_here" }
}
}
}Open a new session in your AI tool and paste:
Go to https://example.com, then finish the recording titled "Setup test"
and give me the link.A browser window opens, and within ~15 seconds the agent replies with a .../tracks/... link. If the video plays — you're set. 🎉
Variable | Required | Description |
| For recording | Personal API key ( |
| No | Override platform URL (default |
| No | Set |
| No | Set |
Recordings show a cursor that moves to every element the agent interacts with, a click ripple, and a caption describing each action (Click — Place order button), so anyone watching the video can follow what happened.
If ffmpeg is installed (brew install ffmpeg / apt install ffmpeg), the idle "agent think time" between actions is automatically cut out before upload — a 5-minute session typically becomes under a minute, with the console/network/action timeline re-synced to the shorter video. Without ffmpeg the full-length video is uploaded as-is.
Paste a VibeCheck track URL and your AI pulls in the full debugging context — no API key needed:
Tool | Description | Image? |
| Full bug report — console logs, network, user actions, vitals | Yes (screenshots) |
| Focused error analysis — console errors + failed network requests | Yes (screenshots) |
| Network deep-dive — failed requests, slow requests, summary table | No |
| Performance report — web vitals, navigation timing, assessment | No |
| User action timeline + auto-generated steps to reproduce | No |
get_trackFetch and format a complete VibeCheck bug report.
Parameters:
url_or_id (required) — Track URL or ID
include (optional) — Sections to include: logs, network, actions, vitals, all
analyze_track_errorsFocused view of errors only — console errors with stack traces and failed network requests with response bodies.
Parameters:
url_or_id (required) — Track URL or ID
get_track_networkDeep analysis of network requests with failed/slow request detection.
Parameters:
url_or_id (required) — Track URL or ID
slow_threshold_ms (optional, default: 1000) — Threshold in ms to flag slow requests
status_filter (optional, default: all) — Filter: all, errors, success
get_track_performanceWeb vitals analysis with ratings and optimization suggestions.
Parameters:
url_or_id (required) — Track URL or ID
get_track_actionsUser action timeline with auto-generated steps to reproduce.
Parameters:
url_or_id (required) — Track URL or ID
action_types (optional) — Filter by type: click, input, scroll, navigation, etc.
For screenshot tracks, get_track and analyze_track_errors return the screenshot image alongside the text report using MCP's ImageContent type. Video tracks return text data only (no video fetch).
git clone https://github.com/kosbay/vibecheck-mcp.git
cd vibecheck-mcp
npm install
npm run build
npm startMIT
Analyze errors in a VibeCheck bug report. Returns a focused view of console errors and failed network requests with stack traces and response bodies.
| Name | Required | Description | Default |
|---|---|---|---|
| url_or_id | Yes | The track URL or ID. Supports URLs like https://app.vibecheck-qa.com/tracks/{id} or just the ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns console errors and failed network requests with stack traces and response bodies. However, with no annotations, it misses behavioral traits like read-only semantics, auth requirements, or rate limits.
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 two sentences with clear front-loading of purpose and return type. Every sentence adds value, with no unnecessary 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?
Given the tool's simplicity (one parameter, no output schema), the description adequately covers purpose and return content. It could be slightly more complete by addressing when to use it compared to siblings, but it is largely sufficient.
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 sole parameter 'url_or_id' is fully described in the schema (100% coverage). The description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not elevate it.
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 it analyzes errors in a VibeCheck bug report, with a specific focus on console errors and failed network requests. This distinguishes it from sibling tools like get_track_network and get_track_performance, which may return broader data.
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 for error analysis but does not explicitly state when to use this tool over alternatives like get_track_actions or get_track_performance. No guidance on when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch and format a VibeCheck bug report. Returns a comprehensive markdown report including console logs, network requests, user actions, and web vitals. For screenshot tracks, also returns the screenshot image.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Sections to include in the output. Defaults to all sections. Options: logs, network, actions, vitals, all | |
| url_or_id | Yes | The track URL or ID. Supports URLs like https://app.vibecheck-qa.com/tracks/{id} or just the ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses what the tool returns (markdown report with sections, screenshot for screenshot tracks). As a read operation with no annotations, this level of detail is adequate, though no mention of side effects or auth needs.
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?
Two sentences, front-loaded with the primary action, efficient and no extraneous information.
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 2 parameters, no output schema, and no annotations, the description covers the key aspects: purpose, output format, included data, and screenshot edge case. Minor gap: no mention of pagination or limits.
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 covers both parameters with descriptions (100% coverage). The tool description adds context about the output but not about the parameters themselves, 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 it fetches and formats a VibeCheck bug report as a comprehensive markdown report, distinguishing it from sibling tools that focus on specific subsets like actions or network.
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?
Implies use for comprehensive reports, but does not explicitly say when to use this vs. the more specific get_track_actions, get_track_network, etc. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get user action timeline from a VibeCheck bug report. Returns a chronological timeline of user interactions, auto-generated steps to reproduce, and an action type breakdown.
| Name | Required | Description | Default |
|---|---|---|---|
| url_or_id | Yes | The track URL or ID. Supports URLs like https://app.vibecheck-qa.com/tracks/{id} or just the ID | |
| action_types | No | Filter by action types (e.g. click, input, scroll, navigation). Omit for all types |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions the return content but does not disclose whether the tool is read-only, has side effects, or requires authentication. The statement 'Get user action timeline' implies a read operation, but it is not explicit.
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?
Two sentences: first sentence states purpose, second describes return structure. No redundant information, well front-loaded.
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?
The tool is simple with 2 parameters and no output schema. The description gives a high-level overview of return content but lacks details about edge cases, error handling, or pagination. For a read-only list tool, this is adequate but not comprehensive.
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 baseline is 3. The description does not elaborate on parameters, but the schema already documents them adequately. No additional meaning is added 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 tool retrieves a user action timeline from a VibeCheck bug report, specifying what it returns (chronological timeline, steps, action breakdown). This distinguishes it from sibling tools like get_track (basic track info) and get_track_errors (error 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?
The description does not provide when or when not to use this tool, nor does it mention alternatives among siblings. It only states what the tool does, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze network requests in a VibeCheck bug report. Returns failed requests with response bodies, slow requests sorted by duration, and a summary table of all requests.
| Name | Required | Description | Default |
|---|---|---|---|
| url_or_id | Yes | The track URL or ID. Supports URLs like https://app.vibecheck-qa.com/tracks/{id} or just the ID | |
| status_filter | No | Filter by status: all, errors (4xx/5xx), success (2xx/3xx). Default: all | all |
| slow_threshold_ms | No | Threshold in ms to flag slow requests. Default: 1000 |
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 describes the tool as analyzing and returning data (read operation), but does not explicitly disclose read-only behavior, side effects, or any restrictions. It is adequate but lacks explicit safety cues.
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 one sentence that efficiently conveys purpose and outputs. It is front-loaded and clear, though slightly wordy with enumeration of outputs. 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?
Given no output schema, the description partially compensates by listing three types of returned data (failed requests, slow requests, summary table). However, it does not specify format or structure, leaving gaps for an agent expecting a particular response.
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 the input schema fully documents the three parameters. The description adds no additional meaning beyond the schema, merely mentioning the tool's outputs. 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 clearly states the tool analyzes network requests in a VibeCheck bug report, listing specific outputs (failed requests with response bodies, slow requests sorted by duration, summary table). This distinguishes it from sibling tools like analyze_track_errors (focuses on errors) and get_track_performance (focuses on performance metrics).
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 use when network request analysis is needed but does not explicitly state when to use this tool over alternatives or provide exclusions. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze performance of a VibeCheck bug report. Returns web vitals with ratings, navigation timing per page, and a performance assessment with optimization suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| url_or_id | Yes | The track URL or ID. Supports URLs like https://app.vibecheck-qa.com/tracks/{id} or just the ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only describes the return value and does not mention side effects, permissions, rate limits, or any read-only/destructive nature. The description omits essential behavioral context for an otherwise straightforward analysis 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?
The description is a single sentence that efficiently conveys the purpose and outputs without any extraneous information. It is front-loaded with the main verb and resource, making it easy to scan.
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?
While the description covers the basic purpose and outputs, it lacks details on error handling, interpretability of web vitals ratings, or any constraints. Given the single parameter and no output schema, the description is minimally adequate but could be more informative for a performance analysis 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?
Schema coverage is 100% with one parameter 'url_or_id' that already has a clear description. The tool description does not add any additional semantics beyond that, so it meets the baseline expectation without adding extra value.
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 analyzes performance of a VibeCheck bug report and enumerates the specific outputs: web vitals, navigation timing, and optimization suggestions. The verb 'analyze' and resource 'performance of a VibeCheck bug report' are precise, and the tool distinguishes itself from siblings like analyze_track_errors or get_track by focusing on performance metrics.
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. It does not mention prerequisites, when not to use it, or how it compares to sibling tools like get_track or get_track_network. The agent is left to infer usage from the name and description.
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.
v0.1.1analyze_track_errorsget_trackget_track_actionsget_track_networkget_track_performanceScored across 5 tools
Each tool targets a distinct aspect of bug report analysis: errors, full report, actions, network, and performance. There is no overlap in their purposes.
All tools use snake_case and follow a verb_noun pattern (analyze_track_errors, get_track, get_track_actions, etc.), with consistent verb prefixing and resource targeting.
Five tools is an ideal count for the scope of analyzing a single bug report, covering all key dimensions without excess or deficiency.
The set covers the full breadth of analysis needs for a VibeCheck bug report: errors, user actions, network requests, performance metrics, and a comprehensive overview. No obvious gaps.
Voice-powered bug reporting with 13 MCP tools. Record bugs by talking; let AI find and fix them.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
