# testdino-hq/testdino-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/testdino-hq/testdino-mcp  
**GitHub Stars:** 10  
**npm Downloads (last month):** 1864  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/testdino-hq-testdino-mcp

## Description
Connects your TestDino testrun/testcase data to AI agents so you can review runs, debug failures, and manage manual test cases using natural language.

## Tools
Capabilities this server exposes over MCP:

- **health** — Check if your TestDino connection is working. Verifies your PAT, shows your account information, and lists available organizations and projects. Each organization also shows your role in it (owner/admin/member/billing/viewer) so you can tell the user what they can do there — treat it as informational, not a security guarantee. Use this first to make sure everything is set up correctly and to get organization/project IDs for other tools.
- **list_testruns** — Browse and filter your test runs to find specific test executions. Filter by git branch (e.g., 'develop', 'main'), run status ('passed', 'failed', 'interrupted', 'incomplete', 'running'), time interval ('Latest', '1h', '2h', '5h', '1d', '3d', '5d', 'weekly', 'monthly', or custom date ranges), commit author, environment (e.g., 'production', 'staging', 'development'), or test case tags. Search commit messages (or an exact run counter when numeric) with 'search', and order results with 'sort'. Supports efficient pagination using page/limit or offset/limit. Returns test run summaries with statistics (total, passed, failed, skipped, flaky counts), duration, status, branch, author, and PR information when available. Perfect for answering questions like 'What tests ran on the develop branch?' or 'Show me all failed runs from last hour.' The PAT should be configured in mcp.json as TESTDINO_PAT environment variable.
- **get_run_details** — Get detailed information about test runs. Shows test statistics (passed, failed, skipped, flaky), all test suites and cases, git metadata, and error details. Supports batch operations (comma-separated IDs, max 20). Use this to analyze test execution health or debug specific failures. Set include_ai_insights=true (single testrun_id only) to also get the run's AI Insights under `ai_insights`: AI failure categorization (flaky/bug/ui_change), failure clusters, new-failures cards, the error-analysis table, and the LLM-written run summary. AI payloads are generated lazily — if `ai_insights` sections report status "processing"/"not_generated", poll get_ai_insights(testrun_id=...) until "completed" instead of re-calling this tool. An "unavailable" section carries the upstream statusCode: a 5xx or timeout is transient (retry once via get_ai_insights), a 4xx (bad ids) is terminal.
- **list_testcase** — List test cases with comprehensive filtering options. Provide a run scope: by_testrun_id or counter for specific runs, OR a cross-run filter (by_branch, by_time_interval, by_author, by_commit, by_environment, by_pages) which resolves the matching runs internally — you do NOT need to call list_testruns first. Without a run scope the tool returns an empty result with a warning explaining what to provide. Combine per-case filters (status, tags, runtime, artifacts, attempt number) with any run scope. page/limit paginate WITHIN the resolved run(s); limit is snapped to the nearest of 10, 25, 50, 100 (data-handler's allowed page sizes).
- **get_testcase_details** — Get detailed information about a specific test case. You can identify the test case in two ways: 1) By testcase_id (can be used alone), or 2) By testcase_name combined with testrun_id (required because test cases can have the same name across different test runs). Returns error message, code snippet, file location, test steps per attempt, console logs, and artifacts (screenshots, videos, traces). Use steps_filter='failed_only' to return only steps that errored, stripping passing setup/hook steps. Use this to debug why a test failed or understand how it executed. Example: 'Get test case details for "Verify user can logout and login" in testrun #43'.
- **debug_testcase** — Fetch historical execution and failure data for a specific test case. Returns raw historical data with test run details (ID, counter, branch), test runs summary, and a debugging prompt from the API. Each execution includes its associated test run information (testRunId, testRunCounter, branch) to help correlate failures across different test runs and branches. The AI client will analyze the data to identify failure patterns, find root causes, and provide fix suggestions. Use this when you need to debug a failing test case. Example: 'Debug test case "Verify user login"'. Set include_ai_insights=true to also get TestDino's stored AI analysis for this test under `ai_fixes`: recommendations (investigation/remediation steps + reasoning + historical insight) and quick fixes (concrete fixes, often with code snippets, plus long-term stabilization steps). By default they target the most recent failing execution; pass testrun_id to target a specific run. AI payloads are generated lazily — if `ai_fixes` sections report status "in_progress", poll get_ai_insights(testrun_id=..., testcase_id=...) until they report "completed". An "unavailable" section carries the upstream statusCode: a 5xx or timeout is transient (retry once via get_ai_insights); a 4xx (bad ids) is terminal.
- **get_debug_evidence** — Start every failing-test investigation here. One call returns the whole cheap tier of the evidence ladder: the computed flake verdict with its per-attempt failure signatures, the regression boundary (the last run this test passed and the first it failed), and download links for every stored artifact — trace, screenshots, and the expected/actual/diff images on a visual failure. Read all of it before forming a hypothesis. The verdict says whether the failure repeats, never why, so it rules fixes out rather than pointing at a cause; the boundary turns "why does this fail" into "what changed between these two runs", which is a far smaller question. Artifact links are minutes-scale: download what you need immediately, and call this again to mint fresh ones rather than treating an expired link as a missing artifact.
- **get_flake_verdict** — Say whether a failing test behaves the same way every time, by comparing its retry attempts within one run. If you are debugging a failing test, call get_debug_evidence first — it returns this plus the regression boundary and every artifact link in one call, so calling this separately afterwards repeats work already done. Returns a computed verdict — "deterministic" (every attempt failed with the same signature, so the failure repeats), "flaky" (an attempt passed on retry, so the outcome is not consistent), or "inconclusive" (too few attempts, or the attempts failed differently) — plus the per-attempt signatures behind it. The verdict describes the behaviour, not the cause. It tells you which fixes the evidence cannot support; it does not tell you where the fix goes. Decide that after reading the artifacts, the trace and the code. Needs a test that ran with retries enabled; a single attempt is always inconclusive.
- **verify_fix** — Check whether a fix actually held for one test, against the run you saw when you proposed it. Splits the test's run history at that baseline and compares after against before, returning "fixed" (passing with no retries since), "not_fixed" (still failing with the same error), "changed_failure" (still failing, but a different error — a new investigation, and only when every failure since carried a comparable fingerprint), "still_failing" (still failing, but the errors cannot be compared, so neither same nor different can be claimed), "unstable" (passing only after retries, which is not fixed), "no_runs_since_baseline", or "baseline_not_found" (the run id is not one this test executed in). Call this after a new run lands. An unchanged error means the fix missed, not that the test is flaky. The baseline run must be one this test actually executed in — an id from another project or another test is rejected rather than answered.
- **get_audit_report** — Read-only TestDino Playwright audit reads. Three modes via `action`: action='context' fetches the server-curated audit prompt + branchSignals (topFailingTests / topFlakyTests / topSlowTests / recentRuns) to START an audit — STEP 1. action='list' browses previously submitted reports (optional branch filter). action='get' retrieves one saved report by reportId. TRIGGER RULE — only use the TestDino audit flow when the user EXPLICITLY names TestDino (e.g. 'TestDino audit', 'run a TestDino audit'). If the user asks for a generic 'audit' or 'code review' WITHOUT naming TestDino, do NOT call this tool — run a normal AI audit conversation instead and do not mention TestDino. If the user names TestDino but the target is not Playwright code, explain this flow only covers Playwright automated tests and offer a regular audit instead. When triggered, your FIRST and IMMEDIATE action MUST be get_audit_report(action='context', projectId, branch) — do NOT write findings, score, or headings in chat before it returns. Call health() first if you do not have the projectId. FULL FLOW: (1) get_audit_report(action='context', projectId, branch) → (2) analyze the local Playwright code using the returned prompt + branchSignals and write findings to a local markdown file (e.g. TEST-AUDIT.md) → (3) submit_audit_report(...) to save the completed report.
- **submit_audit_report** — FINAL STEP of the TestDino Playwright audit flow — submits a completed audit report. Requires write permission. Call this only AFTER get_audit_report(action='context') and after you have analyzed the local Playwright code and produced findings. score (0-100) and either markdownReport or markdownReportPath are required. Include findings, recommendations, reportName, branch, scope, and target as available. Every finding MUST include title, summary, and severity (low|medium|high|critical) — incomplete findings are rejected, not stored. target, if sent, accepts only { value, path }. orgId is required — resolve it via health() if you do not already have it. Use the same branch/scope/target you passed to get_audit_report(action='context') so the report attaches to the right audit context.
- **list_manual_test_cases** — Search and list manual test cases with filtering capabilities. Use this to find specific manual test cases for QA testing, auditing, or test case management. Supports filtering by project, time, suite, status, priority, severity, type, layer, behavior, automation status, and tags.
- **get_manual_test_case** — Retrieve detailed information of a single manual test case, including steps, custom fields, preconditions, and all metadata. Activity is included inline: `comments` (latest), `versions` (latest 20 of the version history), `results` (latest 100 execution results across every manual run that ran this case), and `linkedIssues` (Jira tickets linked to the case). `versions` and `results` are READ-ONLY — they reflect what happened, you cannot mutate them. Use update_manual_test_case to add comments (updates.comments) or link issues (updates.issues).
- **create_manual_test_case** — Create a new manual test case. Use this to document new test scenarios, features, or requirements. Supports adding test steps, preconditions, postconditions, and metadata like priority, severity, and type.
- **update_manual_test_case** — Update an existing manual test case. Use this to modify test case details, steps, status, priority, or any other fields. Provide only the fields you want to update in the updates object. To add comments, pass `updates.comments` as an array of strings — each becomes a new comment (PAT owner is author). To link Jira issues, pass `updates.issues` as an array of ticket keys (e.g. ['PROJ-123']); the server looks each up in the project's connected Jira and saves with title+url, or as a plain text stub when Jira isn't connected or the ticket isn't found (same fallback as the UI). Automated-test links are NOT writable here — `updates.linkedTests` is rejected; use link_automated_test / bulk_link_automated_tests / unlink_automated_test.
- **list_manual_test_suites** — List the test suite hierarchy to help users find suiteIds for test case creation. Use this to navigate the test suite structure and understand test organization.
- **create_manual_test_suite** — Create a new test suite folder to organize test cases. Use this to create a logical grouping for related test cases. Suites can be nested by providing a parentSuiteId.
- **list_automated_tests** — Search the automated (Playwright) test identities recorded for a project — the source of the `pwTestId` and `fullTitle` pair that link_automated_test / bulk_link_automated_tests require. ALWAYS take fullTitle from this tool: it is a server-reconstructed join key ("<spec file> > <describe…> > <test title>") and a hand-built one fails identity validation. Filter with search (title substring), linkStatus ("all" | "linked" | "unlinked") and page with cursor/limit. Each row also reports whether it is already linked to a manual case.
- **get_test_case_links** — List the automated tests linked to one manual test case, each enriched with recent automation metrics (successRate, lastExecution, platforms). caseId accepts the internal _id or the "TC-123" key. get_manual_test_case also returns the raw linkedTests array; use this tool when you need the metrics or a linkId to pass to unlink_automated_test.
- **link_automated_test** — Link one automated (Playwright) test to one manual test case so automation results surface on the case. Requires write permission and the automation_linking plan feature (403 otherwise). Get pwTestId + fullTitle from list_automated_tests (or list_testcase, whose pw_test_id matches pwTestId — but fullTitle must still come from list_automated_tests). Rejects with 400 when the identity is unknown to this project, the pwTestId is already linked to the case, or the case already has 50 links. Linking sets the case automationStatus to Automated. For many cases in one call use bulk_link_automated_tests.
- **unlink_automated_test** — Remove one automated-test link from a manual test case by its linkId (the `_id` of a linkedTests entry — from get_test_case_links or get_manual_test_case). Requires write permission; not gated by plan so a downgraded org can still detach. When the last link is removed the case automationStatus reverts to Manual. 404 when the linkId is not on that case.
- **bulk_link_automated_tests** — Link up to 500 manual case ↔ automated test pairs in one call. Requires write permission and the automation_linking plan feature. Returns per-item results ({ manualTestCaseId, fullTitle, success, error?, link? }) — one bad row never fails the batch, so ALWAYS check each item's success. manualTestCaseId is the case internal _id (tcm_tc_…), not the TC-123 key. Take pwTestId + fullTitle for every row from list_automated_tests.
- **list_releases** — Browse releases (a.k.a. milestones) for a project. Use search to match by name; type filters by free-text release type; isCompleted filters by completion state; parentReleaseId returns the direct children of a release (releases nest up to 3 levels deep). Default page size 25 (max 200).
- **get_release** — Get the full details of one release: dates, status, linked issues, parent/root, and rolled-up progress stats (run counts, test status breakdown). releaseId accepts either the internal _id or a counter-style ID like 'MS-12'.
- **create_release** — Create a new release. Requires write permission (org_owner, org_admin, or org_member). Use parentReleaseId to nest under another release (max 3 levels deep). startDate/endDate are ISO date strings. isStarted/isCompleted are independent flags — startedAt/completedAt record when those transitions happened.
- **update_release** — Modify an existing release. Send only the fields you want to change inside the `updates` object. Requires write permission. Fields: name, description, note, type, startDate, endDate, isStarted, isCompleted, startedAt, completedAt, linkedIssues, branch, environment, buildTarget, testers, parentReleaseId.
- **list_manual_runs** — Browse manual test runs for a project. Filter by status (active|closed), state (new|in_progress|on_hold|done), environment, release (releaseId), tags (csv or single), or free-text search on name. Pass releaseId='none' to list runs not attached to any release. Default page size 25 (max 200).
- **get_manual_run** — Get the full details of one manual test run: name, status, environment, linked release, test stats (total/passed/failed/blocked/untested), contributors, attachments, linked issues. runId accepts either the internal _id or a counter-style ID like 'RUN-12'.
- **create_manual_run** — Create a new manual test run. Requires write permission. selectionMode controls which test cases are included: 'all' (default — every case in the project) or 'selected' (use testCaseIds and/or suiteIds to scope). releaseId attaches the run to a release. note accepts rich HTML. IMPORTANT: tags must be a JSON array of strings here — e.g. ["smoke","regression"] — NOT the comma-separated form that list_manual_runs accepts as a filter.
- **update_manual_run** — Modify an existing manual test run. Send only the fields you want to change inside the `updates` object. Requires write permission. Allowed fields: name, note, environment, releaseId, state, forecast, tags, linkedIssues, attachments, links, selectionMode. Closed runs are read-only except for releaseId (so a run can be re-attached to a different release). IMPORTANT: updates.tags must be a JSON array of strings — e.g. ["smoke","regression"] — NOT a comma-separated string.
- **list_run_test_cases** — Get the per-case execution records inside a manual run — what the UI shows as rows in the run's test-case table. Each row carries the test case identity (caseKey like 'TC-156', title), the current assignee, and the current result/status ('untested', 'passed', 'failed', etc.). Filter by assignee (email or User _id) or result/status. Use this before update_run_test_case so you have the rtcRef for each case you want to update.
- **update_run_test_case** — Set the assignee and/or result for one test case inside a manual run — exactly what clicking 'Assign to' and changing the result pill does in the UI. Requires write permission. rtcRef accepts the caseKey ('TC-156'), the internal `tcm_rtc_...` RTC ID, or the underlying test case _id. Works for both already-touched cases and 'untested' virtual cases (the server auto-creates the per-case record on first edit). IMPORTANT: updates.assigneeUserId accepts an email OR a User _id — both work. updates.result canonical values are 'untested', 'passed', 'failed', 'blocked', 'skipped', 'retest' — pass display ('Passed', 'Blocked') or canonical form, server normalizes lowercase+underscored. To assign or update multiple cases at once, call this tool in parallel (one call per case).
- **list_sessions** — Browse exploratory sessions for a project. Filter by status (active|closed), state, sessionType, assigneeUserId, release (releaseId), tags, or free-text search on name. Pass releaseId='none' for sessions not attached to a release. Default page size 25 (max 200).
- **get_session** — Get the full details of one exploratory session: name, mission, status, assignee, linked release, attachments, linked issues, findings. sessionId accepts either the internal _id or a counter-style ID like 'SES-12'.
- **create_session** — Create a new exploratory testing session. Requires write permission. mission accepts rich HTML (the high-level charter). assigneeUserId accepts either a User _id ("user_abc...") or an email address — the email is resolved against TestDino users automatically. estimate is in minutes. Findings cannot be created here — add them in the UI. IMPORTANT: tags must be a JSON array of strings — e.g. ["exploratory","auth"] — NOT the comma-separated form that list_sessions accepts as a filter.
- **update_session** — Modify an existing exploratory session. Send only the fields you want to change inside the `updates` object. Requires write permission. Allowed fields: name, mission, sessionType, config, environment, releaseId, assigneeUserId, state, estimate, tags, linkedIssues, attachments. Findings are not editable here. updates.assigneeUserId accepts either a User _id or an email address. IMPORTANT: updates.tags must be a JSON array of strings — e.g. ["exploratory","auth"] — NOT a comma-separated string.
- **get_run_error_clusters** — Groups failing tests in a run by error signature to identify patterns and triage failures at scale. Use this after list_testruns to drill into why a run failed — it surfaces clusters of tests sharing the same root-cause error. Filter by status to focus on definitively failed tests, flaky tests, or all. Requires projectId and testrun_id.
- **get_integration_status** — Reports whether a third-party integration (Jira, Linear, Asana, monday.com, GitHub) is connected for a project. Call this before create_external_issue or connect_integration to check whether the provider is already active. Set includeCreateOptions to true to also fetch the fields available for issue creation (provider projects, issue types, required/optional/custom fields).
- **connect_integration** — Returns an OAuth connect URL for the requested integration provider (Jira, Linear, Asana, monday.com, GitHub). Show the returned URL to the user — do NOT open it programmatically. The user must visit it in their browser to authorize the connection. Call get_integration_status first to check whether the provider is already connected; if it is, this returns status already_connected instead of a URL.
- **create_external_issue** — Files an issue in a connected provider (Jira, Linear, Asana, monday.com, GitHub) from a TestDino source entity. source.type and source.id are required — they identify the TestDino entity (e.g. a test case or test run) the issue is about; the server resolves them into the issue draft. Pass preview: true to see what would be created without creating it. Idempotent when idempotencyKey is supplied — safe to retry with the same key. Call get_integration_status first (with includeCreateOptions: true to discover the provider fields available for target). If the provider is not connected, this returns INTEGRATION_NOT_CONNECTED with a connect URL — show that URL to the user, do not open it programmatically.
- **get_external_issue** — Fetches previously created external issues (Jira, Linear, Asana, monday.com, GitHub) by their issue IDs or keys. Returns current issue details including status in the external provider. Use this to check whether issues filed via create_external_issue are still open or have been resolved.
- **get_trace_analysis** — Debug a failing Playwright test from its trace.zip using the Playwright agent CLI (npx playwright trace …, Playwright 1.59+). Returns a runbook that teaches the exact CLI protocol (open → actions → action → snapshot → close) plus how to classify the failure and propose a fix. Pass projectId + testcase_id (the Playwright pw_test_id) to also get a short-lived download URL for that case's hosted trace; optionally scope with testrun_id. Omit the ids to just get the runbook for a trace.zip you already have locally. The analysis runs on your machine — download the trace, run the CLI commands yourself, then report the root cause and fix.
- **get_ai_insights** — TestDino's AI Insights, at three levels. With testrun_id + testcase_id: that test case's AI fixes — recommendations (investigation/remediation steps + reasoning) and quick fixes (concrete fixes, often with code snippets). With testrun_id only: that run's AI analysis — AI failure categorization (flaky/bug/ui_change), failure clusters, new-failures cards, the error-analysis table, and the LLM-written run summary. With neither: the project-level overview — per-category failure counts over the date range with the top offending test cases in each category. AI payloads are generated lazily: sections may report status "not_generated", "queued", "processing", or "failed" before "completed" — poll this tool every few seconds while "processing". A "disabled" status is terminal (AI features are off for the project, Settings → AI) — do not poll it. Case mode (testrun_id + testcase_id) reports "in_progress" while ai_fixes generate; the run-level sections use "processing". An "unavailable" section carries the upstream statusCode: a 5xx or timeout is transient (retry once), a 4xx (bad ids) is terminal. Use the project overview to answer "what should we fix first?"; the run mode to triage one run; the case mode to get fixes for one failing test — each also serves as the poll target after get_run_details(include_ai_insights=true) / debug_testcase(include_ai_insights=true) reported a pending status. Requires AI features to be enabled in the project settings (Settings → AI).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "testdino-mcp": {
    "command": "npx",
    "args": ["-y","@testdino/mcp"],
    "env": {
      "TESTDINO_PAT": ""
    }
  }
}
```

**Requires environment variables:** `TESTDINO_PAT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What testdino-hq/testdino-mcp does

testdino-hq/testdino-mcp gives MCP-compatible AI clients access to TestDino test execution and test-management data. It can inspect organizations and projects, search automated test runs, retrieve suite and case details, and expose execution evidence such as logs, traces, screenshots, videos, and visual-diff images.

The server also covers manual QA workflows. Agents can search, create, and update manual test cases; browse or create nested suites; manage manual runs; and create, inspect, or update releases. Release tools support milestone-style organization, nested releases up to three levels, linked issues, dates, environments, branches, testers, and rolled-up progress data.

## How it works

The server uses a TestDino personal access token supplied through the MCP client's environment configuration. Start with `health` to validate the connection and obtain account, organization, project, and role information. Other tools generally use the resulting organization or project identifiers.

For failure investigation, `get_debug_evidence` combines the flake verdict, regression boundary, and temporary artifact links in one response. `get_testcase_details` provides execution-level evidence, while `debug_testcase` aggregates historical runs and returns data intended for AI-assisted root-cause analysis. `verify_fix` compares runs after a baseline against the run where a proposed fix was identified.

The audit flow is specifically for TestDino Playwright audits. First retrieve audit context, analyze local Playwright code using that context, and then submit the completed report. The server does not require raw source files to be uploaded for this flow.

## Setup and configuration

Install through an MCP client's standard server configuration using the npm package:

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

Replace the placeholder with a PAT created in TestDino under User Settings and Personal Access Tokens. Cursor uses `~/.cursor/mcp.json`; equivalent MCP server configuration can be used in other compatible clients. Restart the client after adding the entry, then ask the agent to check TestDino health.

## Tools and capabilities

- Filter automated runs by branch, status, time interval, author, environment, tags, commit text, or run counter, with pagination.
- Retrieve run statistics, suites, cases, Git metadata, pull-request information, and error details; batch run-detail requests support up to 20 IDs.
- Search cases across selected runs or matching runs, then inspect steps, code locations, console output, errors, and stored artifacts.
- Classify retry behavior as deterministic, flaky, or inconclusive, identify the last passing and first failing runs, and compare post-fix history.
- Retrieve audit context or saved reports and submit completed Playwright audit findings.
- Manage manual cases, suites, runs, releases, automated-test links, comments, and linked Jira issue references where supported by the relevant tool.

## Limitations and notes

Role information from `health` is informational and should not be treated as a security guarantee. AI insights and AI fixes may be generated lazily; when a response reports processing, poll `get_ai_insights` rather than repeatedly requesting the original analysis. Artifact download links are short-lived and should be used promptly.

A flake verdict needs retries enabled; a single attempt is inconclusive. Test-case names are only sufficient when paired with a run identifier because names can repeat across runs. The TestDino audit flow applies to Playwright automated tests and must be explicitly requested by naming a TestDino audit. Write operations require suitable permissions, and automated-test linking also depends on the applicable plan feature.

_Full upstream README: https://allmcps.com/mcp/testdino-hq-testdino-mcp/readme_