testdino-hq/testdino-mcp

A Model Context Protocol (MCP) server that connects TestDino to AI agents. This server enables you to interact with your TestDino test data directly through natural language commands.

Quick Start

Add this to your MCP client config (~/.cursor/mcp.json for Cursor), then restart the client:

{
  "mcpServers": {
    "TestDino": {
      "command": "npx",
      "args": ["-y", "@testdino/mcp"],
      "env": {
        "TESTDINO_PAT": "your-pat-here"
      }
    }
  }
}

Get your PAT from TestDino → User Settings → Personal Access Tokens, then ask your assistant: "Check TestDino health." You should see your account, organizations, and projects. Full setup for Cursor and Claude Desktop is in Integration.

What is This?

This MCP server bridges the gap between your TestDino test management platform and AI agents. Instead of manually navigating the TestDino dashboard, you can ask your AI assistant to:

• Check test run results
• Analyze test failures
• Get detailed test case information
• Manage manual test cases and suites
• Plan releases, spin up manual test runs, and assign testers
• Run exploratory testing sessions
• Record per-case verdicts (passed / failed / blocked / etc.) from chat

All through simple conversational commands.

Features

• 🔍 Health Check: Verify your connection and validate your TestDino PAT. Get account information and list all available organizations and projects.
• 📊 Test Run Management: List and retrieve detailed information about your test runs with filtering options (branch, time, author, commit, environment).
• 🧪 Test Case Analysis: Get comprehensive details about individual test cases, including errors, logs, execution steps, and artifacts (screenshots, videos, traces).
• 🐛 AI-Assisted Debugging: Debug test case failures with historical data aggregation, failure pattern analysis, and AI-friendly debugging prompts. Analyze patterns across multiple executions to identify root causes.
• 🧭 Test Quality Audit: Fetch a server-curated audit prompt plus branch signals, analyze your local test code, and store the completed report back in TestDino without uploading raw source files.
• 📝 Test Case Management: Create, update, list, and retrieve manual test cases with comprehensive filtering and organization (status, priority, severity, type, layer, behavior, tags).
• 📁 Test Suite Organization: Create and manage test suite hierarchies to organize your manual test cases.
• 🚀 Release Planning: Create, browse, and update releases (a.k.a. milestones), nest them up to 3 levels deep, and track rolled-up progress stats across all runs in a release.
• ▶️ Manual Test Runs: Spin up runs scoped to specific suites or the whole project, attach them to a release, and update workflow state without leaving chat.
• ✅ Per-case Assignment & Verdicts: Inside a run, assign each test case to a tester (by User _id or email) and set the result — passed, failed, blocked, skipped, retest — exactly as the UI does.
• 🔭 Exploratory Sessions: Create exploratory testing sessions with mission/charter, assign a tester, link to a release, and track state.
• 🧩 Failure Triage at Scale: Group a run's failing tests by their underlying error signature to see which reds are one root cause versus many, so you fix the real problem first.
• 🔗 Issue Tracker Integrations: Connect Jira, Linear, Asana, or monday.com and file a tracked issue straight from a failing test or run, then check its status later without leaving chat.
• 🔌 MCP Compatible: Built on the Model Context Protocol standard. You can configure TestDino MCP with any MCP-compatible IDEs or AI agents (Cursor, Claude Desktop, etc.).
• ⚡ Easy Setup: Install and configure in minutes with npx. No installation required!
• 🔐 Secure: PAT stored securely in your local configuration. One PAT provides access to all organizations and projects you have permissions for.

Available Tools

The server provides 57 tools across twelve domains, the same tools, prompts and skills guide as the hosted TestDino MCP:

Test Execution & Results:

1. health - Verify your connection and validate your PAT. Shows account information, available organizations, and projects with access permissions.
2. list_testruns - Browse test runs with filters (branch, time interval, author, commit, environment). Supports pagination and batch operations.
3. get_run_details - Get comprehensive details about a specific test run including statistics, test suites, test cases, and metadata. Supports batch operations (comma-separated IDs, max 20).
4. list_testcase - List test cases with comprehensive filtering (by test run, status, browser, error category, branch, environment, commit, author, spec file, tags, runtime, artifacts, and more). Can filter by test run criteria or directly by test case properties.
5. get_testcase_details - Get detailed information about a specific test case including error messages, stack traces, test steps, console logs, and artifacts. Can identify by testcase_id alone or by testcase_name with testrun_id/counter.
6. debug_testcase - Debug a test case by aggregating historical failure data across multiple executions. Returns failure patterns, error categories, common error messages, error locations, browser-specific issues, and a pre-formatted debugging prompt for AI analysis. Perfect for root-cause analysis and identifying flaky test behavior.
7. get_debug_evidence - Start every failing-test investigation here: one call returns the flake verdict with per-attempt signatures, the regression boundary (last pass → first fail), and short-lived download links for every stored artifact (trace, screenshots, visual diff images). JSON or markdown.
8. get_flake_verdict - Compare a test's retry attempts within one run and say whether the failure repeats: deterministic, flaky, or inconclusive.
9. verify_fix - After a new run lands, check whether a fix held against the run you saw the failure in: fixed, not_fixed, changed_failure, still_failing, unstable, no_runs_since_baseline, or baseline_not_found.
10. get_audit_report - Fetch the audit context (server-curated prompt + top failing / flaky / slow tests for the branch) to start a new audit, browse historical reports, or retrieve one by reportId.
11. submit_audit_report - Submit a completed audit report (score, findings, recommendations, markdown) to TestDino.

Test Case Management:

1. list_manual_test_cases - Search and list manual test cases with comprehensive filtering (project, suite, status, priority, severity, type, layer, behavior, automation status, tags, flaky status).
2. get_manual_test_case - Get detailed information about a specific manual test case including steps, custom fields, preconditions, postconditions, and all metadata.
3. create_manual_test_case - Create new manual test cases with steps, preconditions, postconditions, and metadata (priority, severity, type, layer, behavior).
4. update_manual_test_case - Update existing manual test cases (title, description, steps, status, priority, severity, type, layer, behavior, preconditions, postconditions).
5. list_manual_test_suites - List test suite hierarchy to find suite IDs for organization. Supports filtering by parent suite.
6. create_manual_test_suite - Create new test suite folders to organize test cases. Supports nested suites by providing parentSuiteId.

Automation Linking:

1. list_automated_tests - List the Playwright tests TestDino has seen for a project, the source of pwTestId + fullTitle for linking. Filter by spec file, suite, or free-text title.
2. get_test_case_links - Show which automated tests are linked to a manual test case, with their latest automation result.
3. link_automated_test - Link one Playwright test to a manual test case so its automation result shows on the case.
4. unlink_automated_test - Remove a link between a manual test case and a Playwright test.
5. bulk_link_automated_tests - Link up to 500 case/test pairs in one call, with per-item results so a partial failure is visible.

Releases (a.k.a. Milestones):

1. list_releases - Browse releases for a project with filters (search, type, completion status, parent release). Releases group runs + sessions and can nest up to 3 levels deep.
2. get_release - Get full details for one release including dates, status, parent/root hierarchy, and rolled-up progress stats across all runs in this release and its descendants. Accepts internal _id or counter-style ID like MS-12.
3. create_release - Create a new release with name, type, dates, and optional parent for nesting.
4. update_release - Modify an existing release — name, dates, completion flags, type, linked issues. Closed releases are still editable.

Manual Test Runs:

1. list_manual_runs - Browse manual runs in a project. Filter by status, state, environment, release, tags, or free-text name search.
2. get_manual_run - Get full details for one run — test stats (total/passed/failed/blocked/untested), contributors, attachments, linked release. Accepts internal _id or counter-style ID like RUN-12.
3. create_manual_run - Create a new manual run. Choose selectionMode='all' for every case in the project, or 'selected' with suite/case IDs to scope it. Attach to a release with releaseId.
4. update_manual_run - Modify run metadata — name, environment, state, release attachment, tags. Closed runs are read-only except for releaseId.
5. list_run_test_cases - Get the per-case execution rows inside a run — exactly what the UI shows in the run's test-case table. Each row includes the current assignee and current result. Filter by assignee (email or _id) or result.
6. update_run_test_case - Set the assignee and/or result for one test case inside a run — same as clicking "Assign to" + the result pill in the UI. Works even on untested cases (auto-creates the per-case row on first edit). Accepts caseKey (TC-156), test case _id, or the internal tcm_rtc_… ID.

Exploratory Sessions:

1. list_sessions - Browse exploratory sessions in a project. Filter by status, state, sessionType, assignee (email or _id), release, tags.
2. get_session - Get full details for one session — name, mission, status, assignee, linked release, findings. Accepts internal _id or counter-style ID like SES-12.
3. create_session - Create a new exploratory session with mission/charter, sessionType, assignee, estimate, and optional release attachment.
4. update_session - Modify session metadata — name, mission, assignee, state, estimate, linked issues, attachments.

Error Analysis:

1. get_run_error_clusters - Group a run's failing tests by error signature to triage at scale. Surfaces clusters of tests that share the same root-cause error, with an optional status filter (all, failed, flaky). Use it after list_testruns to understand why a run failed.

Integrations (Issue Trackers):

1. connect_integration - Return an OAuth connect URL for a provider (Jira, Linear, Asana, monday.com, GitHub). Show the URL to the user to authorize; do not open it programmatically.
2. get_integration_status - Report whether a provider is connected for a project. Set includeCreateOptions to also fetch the fields available for issue creation. Call this before create_external_issue.
3. create_external_issue - File an issue in a connected tracker (Jira, Linear, Asana, monday.com) from a TestDino source entity such as a failing test case or run. Supports preview and idempotent retries via idempotencyKey.
4. get_external_issue - Fetch previously created issues by their IDs or keys (one or many) and return their current status in the provider (Jira, Linear, Asana).

Provider support: All providers can be connected and status-checked. Issue creation works with Jira, Linear, Asana, and monday.com. Issue read-back works with Jira, Linear, and Asana. GitHub is supported as a PR/CI integration, not an issue tracker.

AI Insights:

1. get_ai_insights - TestDino's AI analysis at three levels: project overview (per-category failure counts + top offenders over a date range), run (AI failure categorization, failure clusters, error-analysis table, LLM-written summary), and test case (recommendations + quick fixes). Returns a disabled status when AI features are turned off for the project (Settings → AI).
2. get_trace_analysis - Resolve a failing test's hosted Playwright trace to a short-lived download URL and return a runbook for local trace-CLI debugging (open → actions → snapshot → close).

Re-run:

1. get_rerun_selection - Work out which of a finished run's tests a re-run would execute — failed, flaky, both, or a hand-picked list — as the exact Playwright --test-list lines plus the CLI command that runs them locally. Also returns rerun_mechanism: whether a same-commit re-run would happen inside the run's own GitHub run (so that red check can turn green) or start a separate workflow run, and why. Read-only; nothing runs.
2. rerun_test - Start the re-run in CI. Needs confirm: true after the user says yes, and needs mode — same-commit (the commit that failed: are these failures real, or flaky?) or latest (the branch tip: did my fix work?). There is no default mode; an omitted one is refused so the choice reaches the user. Every refusal happens before anything is dispatched.

Ask first. Call get_rerun_selection, show the user what would run and what rerun_mechanism says, then ask which mode they want. Re-runs cost CI minutes.

Test Controls (quarantine, critical, assignee, watch):

1. list_test_controls - List the tests under Test Controls as the Test Controls page shows them: quarantined (active, ending soon, released), critical, the tests you watch, or flaky candidates for quarantine.
2. get_test_controls - One test's assignee, critical flag, watch state and active quarantine, plus the runs a quarantine kept from failing in the last 90 days.
3. get_quarantine - One quarantine with its full history and the runs it covered.
4. quarantine_tests - Quarantine 1–100 tests until an end date, with a required reason; dry_run shows what would happen first.
5. update_quarantine - Extend a quarantine, change its assignee or note, or link a ticket.
6. release_quarantine - End a quarantine now; the test's failures fail the build again.
7. set_test_critical - Mark or unmark a test critical (owners and admins).
8. assign_test - Assign a test by email, user id or "me", or unassign it.
9. watch_test - Watch or stop watching a test.

Account, projects and pull requests:

1. get_org_details - Plan, executions left and when they reset, what happens when they run out, seats and projects against the plan, extra executions, and per-project test health.
2. get_project_details - One project's health, usage, connected integrations, branch → environment mapping, and the top 10 flaky, slow, failing, chronic and slowing tests.
3. get_pull_requests - The newest pull requests and their latest test run, or one pull request with its test runs.

Ask first. Quarantining, releasing and marking critical change what fails the build; the tools are flagged destructive so your client asks before running them.

Prompts: testdino_guide (the skills guide), fix_run (triage a failing run into a fix plan), fix_case (root-cause one failing test), fix_flake (route a retried failure to the right kind of fix) and optimize_swarm (why a multi-machine run took as long as it did, and the one change that would help).

AI Insights are also available inline: pass include_ai_insights: true to get_run_details (attaches the run's AI Insights under ai_insights) or debug_testcase (attaches recommendations + quick fixes under ai_fixes).

Installation Options

There are mainly 3 options to use TestDino MCP:

Option 1: Via npx (Recommended - No Installation)

• No installation required
• Automatically downloads and runs when needed
• Always uses the latest version
• Configured in any MCP compatible platform

Option 2: Global Installation

npm install -g @testdino/mcp

• Install once, use in any project
• Requires Node.js 20+ and npm
• Use command: testdino-mcp

Option 3: Project Installation

npm install @testdino/mcp

• Installed in your project's node_modules
• Use command: npx @testdino/mcp

Integration

A simple Integration guide for Cursor IDE:

Step 1: Get Your Personal Access Token (PAT)

1. Log in to your TestDino account
2. Navigate to User Settings → Personal Access Tokens
3. Generate a new PAT from the Personal Access Tokens section.
4. Important: This PAT provides access to all organizations and projects you have permissions for

Step 2: Configure Cursor

1. Open or create the MCP configuration file:

   • Windows: %APPDATA%\Cursor\mcp.json
   • macOS/Linux: ~/.cursor/mcp.json
   • Project-specific: .cursor/mcp.json in your project root

2. If you are using npx or installing inside project, Add the configuration:

{
  "mcpServers": {
    "TestDino": {
      "command": "npx",
      "args": ["-y", "@testdino/mcp"],
      "env": {
        "TESTDINO_PAT": "Your PAT here"
      }
    }
  }
}

Important: Replace Your PAT here with your actual Personal Access Token (PAT) from Step 1.

Step 3: Restart and Verify

1. Completely close and restart Cursor
2. Verify the connection by asking: "Check TestDino health"
3. You should see your account name, available organizations, and projects!

Alternative: Global Installation

If you prefer to install globally instead of using npx or project installation:

npm install -g @testdino/mcp

Then use this configuration:

{
  "mcpServers": {
    "TestDino": {
      "command": "testdino-mcp",
      "env": {
        "TESTDINO_PAT": "Your PAT here"
      }
    }
  }
}

The server uses the standard MCP protocol, so it will work with other MCP-compatible clients as well.

Claude Desktop

Claude Desktop uses the same config shape, in a different file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "TestDino": {
      "command": "npx",
      "args": ["-y", "@testdino/mcp"],
      "env": {
        "TESTDINO_PAT": "your-pat-here"
      }
    }
  }
}

Restart Claude Desktop, then ask "Check TestDino health" to verify.

Local development

By default the server talks to https://mcp.testdino.com. To point it at a local API while developing, set TESTDINO_API_URL (see .env.example):

TESTDINO_API_URL=http://localhost:3001

Usage

Once configured, simply talk to your AI assistant in natural language. Important: Tools require your Personal Access Token (PAT) configured as TESTDINO_PAT in mcp.json. The PAT automatically provides access to all organizations and projects you have permissions for.

Example Commands

Try these natural language commands in Cursor or Claude Desktop (or other MCP-compatible clients):

Connection & Setup:

• "Check if my TestDino connection is working"
• "Validate my TestDino PAT"

Exploring Test Runs:

• "Show me my last 5 test runs"
• "What test runs are on the develop branch?"
• "List test runs from the last 3 days"
• "Show me test runs by author john"
• "Find test runs for commit abc123"
• "List all test runs in production environment"

Analyzing Test Results:

• "Get details for test run test_run_6901b2abc6b187e63f536a6b"
• "Get details for test run counter 42"
• "What test cases failed in test run test_run_6901b2abc6b187e63f536a6b?"
• "Show me all flaky tests from the last test run"
• "List all failed test cases in production environment"
• "Show me test cases from the main branch that took more than 100 seconds"
• "Find all timeout issues in test cases from commit abc123"

Debugging Test Failures:

• "Debug test case 'Verify user login' in project proj_123"
• "Debug 'Verify that User Can Complete the Journey from Login to Order Placement @webkit' from testdino reports"
• "Analyze failures for 'Checkout flow' test case in project proj_123"
• "What are the failure patterns for 'API authentication' test?"
• "Why is test case 'User registration' failing?"
• "Debug test case 'Verify that user can login and logout successfully @chromium'"

Managing Manual Test Cases:

• "List all manual test cases in project proj_123"
• "Search for manual test cases with tag 'smoke' in project proj_123"
• "Show me all critical priority manual test cases in project proj_123"
• "Get details for manual test case TC-123 in project proj_123"
• "Create a new manual test case for login feature in suite Authentication Tests"
• "Update test case TC-123 to mark it as deprecated"
• "List all test suites in project proj_123"
• "Create a new test suite called 'Authentication Tests' in project proj_123"

Releases:

• "List all releases in project proj_123"
• "Show me the open iterations on this project"
• "Get details for release MS-12 and show the rolled-up test progress"
• "Create a release called 'Sprint 42' as an iteration from May 12 to May 26"
• "Mark release MS-12 as completed"

Manual Test Runs:

• "List manual runs in release MS-12"
• "Show me all in-progress runs on staging"
• "Get details for run RUN-7"
• "Create a manual run called 'Sprint 42 Smoke' linked to release MS-12 on staging, covering the Authentication suite"
• "Set run RUN-7's state to Done"
• "Re-attach run RUN-7 to release MS-13"

Assigning Cases & Recording Verdicts in a Run:

• "List the test cases in run RUN-1 with their current assignees and results"
• "Assign TC-156 in run RUN-1 to alice@company.com and mark it Passed"
• "Mark TC-157 in run RUN-1 as Failed"
• "Assign TC-158 in run RUN-1 to bob@company.com — leave the result untested"
• "Show me all cases in run RUN-1 assigned to alice@company.com that are still untested"

Exploratory Sessions:

• "List active exploratory sessions for project proj_123"
• "Show me sessions assigned to tester@company.com"
• "Get details for session SES-3"
• "Create an exploratory session called 'Auth charter — May 12' with mission 'find session-handling bugs around 2FA' assigned to tester@company.com, 60 minute estimate"
• "Update session SES-3 to mark it Done"

Documentation

• Installation Guide: Detailed setup instructions for Cursor, Claude Desktop, and other MCP-compatible clients
• Tools Documentation: Per-tool reference with examples, parameters, and use cases
• AI Agent Skills Guide: Guide for AI agents on tool selection patterns, decision trees, and best practices

Requirements

• Node.js: Version 20.0.0 or higher
• NPM: Latest version recommended (for package management)
• TestDino Account: Valid account with Test Runs and/or Test Case Management access
• Personal Access Token (PAT): Required for authentication. Get it from TestDino Settings → Personal Access Tokens

Key Features Explained

AI-Assisted Debugging with debug_testcase

The debug_testcase tool helps you understand why tests are failing by analyzing historical execution data:

• Historical Analysis: Aggregates data from multiple test runs to identify patterns
• Failure Patterns: Identifies common error categories, messages, and locations
• Browser-Specific Issues: Detects browser-specific failure patterns
• Flaky Test Detection: Analyzes retry patterns and flakiness indicators
• AI-Friendly Output: Returns pre-formatted debugging prompts for AI analysis
• Code Correlation: Provides file and line numbers for error locations, enabling AI to correlate with source code

Example Workflow:

1. Ask: "Debug test case 'Verify user login' from testdino reports"
2. AI calls debug_testcase with projectId and testcase_name
3. Tool returns historical data with failure patterns
4. AI analyzes the data and correlates with your test code (if accessible)
5. AI provides specific fix suggestions based on patterns and code analysis

Support

• Documentation: See docs/TOOLS.md for complete tool documentation
• Installation Help: See docs/INSTALLATION.md for detailed setup instructions
• TestDino Support: support@testdino.com
• TestDino Documentation: https://docs.testdino.com