TestCollab MCP Server
Manage TestCollab test cases, test plans, and suites from an MCP-compatible AI client.
Get project context (suite tree, tags, custom fields, requirements, folders, releases, users) to resolve names to IDs.
List, retrieve, create, and update test cases with filtering, sorting, pagination, steps, step patches, tags, requirements, custom fields, and attachments.
List and retrieve test plans with filters (status, priority, release, folder, dates, creator), sorting, pagination, runs, and configurations.
Create, update, and delete test plans, including test case selection by IDs/selector, configurations, assignments, custom fields, release/folder association, and status.
List the suite tree and create, retrieve, update, delete, move, and reorder suites.
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., "@TestCollab MCP Server Show me all high-priority test cases in the Login suite"
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.
TestCollab MCP Server
Connect your AI coding assistant to TestCollab — manage test cases, test plans, and suites directly from Claude, Cursor, Windsurf, Codex, or any MCP-compatible client.
Quick Start
1. Get your API token
Log in to TestCollab → My Profile Settings → API Token tab → Generate new API token.
2. Add the server to your MCP client
Claude Code — add to .mcp.json in your project root:
{
"mcpServers": {
"testcollab": {
"command": "npx",
"args": ["-y", "@testcollab/mcp-server"],
"env": {
"TC_API_TOKEN": "your-api-token",
"TC_API_URL": "https://api.testcollab.io",
"TC_DEFAULT_PROJECT": "16"
}
}
}
}Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"testcollab": {
"command": "npx",
"args": ["-y", "@testcollab/mcp-server"],
"env": {
"TC_API_TOKEN": "your-api-token",
"TC_API_URL": "https://api.testcollab.io",
"TC_DEFAULT_PROJECT": "16"
}
}
}
}Codex - register TestCollab from the command line:
codex mcp add testcollab \
--env TC_API_TOKEN=your-api-token \
--env TC_API_URL=https://api.testcollab.io \
--env TC_DEFAULT_PROJECT=16 \
-- npx -y @testcollab/mcp-serverOr add the server to ~/.codex/config.toml for all projects, or .codex/config.toml in a trusted project:
[mcp_servers.testcollab]
command = "npx"
args = ["-y", "@testcollab/mcp-server"]
[mcp_servers.testcollab.env]
TC_API_TOKEN = "your-api-token"
TC_API_URL = "https://api.testcollab.io"
TC_DEFAULT_PROJECT = "16"Run codex mcp list to confirm the server is configured. See the official Codex MCP documentation for configuration scopes and additional options.
Cursor — add to .cursor/mcp.json in your project root:
{
"mcpServers": {
"testcollab": {
"command": "npx",
"args": ["-y", "@testcollab/mcp-server"],
"env": {
"TC_API_TOKEN": "your-api-token",
"TC_API_URL": "https://api.testcollab.io",
"TC_DEFAULT_PROJECT": "16"
}
}
}
}Manual Testing
TC_API_TOKEN=your-token npm startRelated MCP server: Testmo MCP Server
Available Tools
list_test_cases
List test cases from a project with optional filtering.
Parameters:
Name | Type | Required | Description |
| number | No* | Project ID (*required if |
| number|string | No | Filter by suite ID or title |
| object | No | Filter conditions |
| array | No | Sort specification |
| number | No | Max results (1-100, default: 50) |
| number | No | Skip N results (default: 0) |
3. Verify
Restart your client, then ask: "What tools do you have for TestCollab?"
You should see the TestCollab tools listed. Try: "Show me all test cases".
Configuration
Variable | Required | Default | Description |
| Yes | — | API token from your TestCollab profile |
| No |
| TestCollab API base URL |
| No | — | Default project ID (makes |
EU region: If your TestCollab account is hosted in the EU, use
https://api-eu.testcollab.ioas yourTC_API_URL.
What You Can Do
Tool | Description |
get_project_context | Get suites, tags, custom fields, requirements, test plan folders, releases, users — call this first |
list_test_cases | Query test cases with filtering, sorting, and pagination |
get_test_case | Fetch a test case with full step details |
create_test_case | Create a test case with steps, tags, custom fields |
update_test_case | Update any test case field |
list_test_plans | List test plans with filtering/sorting (including release ID/title filters) |
get_test_plan | Fetch one test plan with included test cases count, configurations, runs, current progress status, and release info |
create_test_plan | Create a test plan with cases selected by IDs, selectors, or tag ID/name; preserve default assignees unless overridden |
get_test_plan_cases | Get case steps, expected results, configuration statuses and assigned execution IDs for a run |
report_test_case_result | Record one execution with status, comments, milliseconds, step results and evidence files |
report_results | Report a structured batch, set plan custom fields and optionally skip omitted assignments |
update_test_plan | Update test plan metadata, status, assignment, and release association |
delete_test_plan | Delete a test plan |
list_suites | List all test suites in a project (supports |
get_suite | Get suite details |
create_suite | Create a new suite |
update_suite | Update a suite |
delete_suite | Delete a suite |
move_suite | Move a suite to a different parent |
reorder_suites | Reorder suites within a parent |
Example Prompts
"Show me all high-priority test cases in the Login suite"
"Create a test case for verifying password reset with 5 steps"
"List all test plans created this week"
"Create a regression test plan with all test cases tagged 'smoke'"
"Move the Payment suite under the Checkout suite"See Use Cases for detailed workflows.
Execute a plan through MCP
Create a tagged plan using the existing creation flow:
{
"title":"Smoke tests",
"test_cases":{"tag_name":"Smoke","assignee":"me"},
"override_assignees":false
}test_cases.tag_id selects a numeric project tag instead. Use one tag reference;
tag selection can include additional selector filters, and is separate from
explicit test_case_ids. Existing case, configuration, assignment, release,
folder and custom-field options remain available. With override_assignees
omitted or false, default case assignees are kept and the supplied assignee fills
only unassigned cases. Set it to true to replace defaults.
Call get_test_plan_cases with test_plan_id. Also supply run_id to get the
token owner's assigned execution IDs and the run's revision steps. The response
includes testCases, configurations, statuses with active systemName values,
and executions. Use these internal IDs; TC- display numbers are different IDs.
For data-driven cases, each case includes datasets with id, name,
parameters and rows (index plus values). Each execution includes its saved
datasets and datasetResults. Use the execution's snapshots for a run; later
library edits can change the case's current datasets.
Report one assigned execution with report_test_case_result:
{
"run_id":365,
"executed_test_case_id":53404,
"status":"passed",
"comment":"Login succeeded",
"time_taken":1200,
"step_results":[{
"step":"Sign in","expected_result":"Home page appears","status":"passed",
"attachments":[{"file_name":"step.log","content_base64":"T2sK"}]
}],
"attachments":[{"file_name":"run.log","content_base64":"T2sK"}]
}step_results are matched to the run's steps by position: each saved step keeps its
text and expected result, and takes the status and comment you send. A step you do not
send takes the case status. Send at most one result per step. Status uses an active system name, including custom statuses. time_taken adds
milliseconds (the CLI's tc reportCase --time-taken takes seconds). The token determines the executor;
results record execution_source: agent ("Agent" in the Run Mode column) and
execution_context.tool: tc-mcp-server. TestCollab counts an agent result as machine-executed.
Each step_results item accepts an optional attachments list in the same format
as the top-level list. Step files appear under that step, and previously saved
step files are kept. Top-level files belong to the whole result.
Attachments allow up to 10 files per call, across the result, steps and dataset rows. In stdio mode, use
{"file_path":"/path/to/screenshot.png"} for a local regular file up to 10 MB.
You can also use file_name plus standard padded content_base64 for
up to 1 MB decoded per file. Omit data-URL prefixes. Optional mime_type overrides
file-extension detection.
For a data-driven execution, send dataset_results instead of step_results:
{
"run_id":365,
"executed_test_case_id":53404,
"status":"failed",
"dataset_results":[
{"dataset_id":7,"dataset_row_index":0,"step_index":0,"status":"passed"},
{"dataset_id":7,"dataset_row_index":1,"step_index":0,"status":"failed",
"comment":"This account could not sign in",
"attachments":[{"file_name":"failure.log","content_base64":"T2sK"}]}
]
}Copy dataset_id, dataset_row_index and step_index from the execution's
datasetResults; indexes start at zero. Each supplied entry changes that row
and step only. Unreported entries keep their status, comment and files. New files
are added to existing files on the selected entry. The 10-file limit covers
top-level, step and row files together. The case status must rank at least as high
as all saved row statuses in the project's status vocabulary. Duplicate or
unknown coordinates and inactive statuses are refused before uploads or writes.
Row files are uploaded and linked to the execution before saving their IDs in
the row results. If the result write then fails, those files remain linked to
the execution and no time has been added.
Invalid evidence is checked before result writes. Errors after a saved result identify a failed time/evidence update; repeating the time update can add it twice. Step files are uploaded and linked to the execution before their IDs are saved on the steps. If that upload or link fails, the result and time are not updated.
For report_results, pass test_plan_id and a nonempty results array:
{
"test_plan_id":131,
"results":[{"test_case_id":1724,"configuration_id":9,"status":"passed","time_taken":1200}],
"skip_missing":true,
"custom_fields":[{"id":5,"name":"environment_text","value":"staging","valueLabel":"staging"}]
}Optional run_id selects a run; otherwise the latest run is used. The caller's
assigned executions are matched by internal case and configuration IDs.
configuration_id is required when more than one assigned execution matches.
Invalid and duplicate targets are refused before writes. Custom fields use API
IDs, system names and typed values; unspecified existing values are kept.
skip_missing marks omitted caller assignments skipped after supplied results
succeed. The response lists confirmed results, skipped IDs and per-execution
errors. Check it before retrying a partial failure. Batch evidence can be attached
through report_test_case_result. File parsing, auto-create and builds are outside
this execution flow.
See execution architecture and verification.
Local Development Setup
If you're contributing or want to run from source instead of npx:
git clone <repo-url>
cd tc-mcp-server
npm install
npm run buildThen point your MCP client to the built file:
{
"mcpServers": {
"testcollab": {
"command": "node",
"args": ["/path/to/tc-mcp-server/dist/index.js"],
"env": {
"TC_API_TOKEN": "your-api-token",
"TC_API_URL": "http://localhost:1337",
"TC_DEFAULT_PROJECT": "16"
}
}
}
}Dev Commands
npm run dev # Watch mode with hot reload
npm run build # Compile TypeScript
npm test # Run tests
npm run typecheck # Type check
npm run lint # LintTroubleshooting
Server not appearing in your client
Restart the client after adding the config
Verify Node.js 20+ is installed:
node --versionTest manually:
TC_API_TOKEN=your-token npx @testcollab/mcp-server
Authentication errors
Verify your API token is valid and not expired
Check that
TC_API_URLpoints to the correct server
"project_id is required" error
Set
TC_DEFAULT_PROJECTin your env config, orSpecify the project in your prompt: "Show me test cases in project 16"
License
MIT
Available Tools
20 toolscreate_suiteA
Create a new test suite in TestCollab. Tip: Call get_project_context first to see existing suites and resolve parent suite names to IDs.
Required: title Optional: project_id, parent (suite ID or title), description
Examples: Root suite: { "title": "Authentication" } Child suite: { "title": "Login", "parent": "Authentication" } With description: { "title": "API Tests", "description": "Tests for REST API endpoints" }
Inputs: title (required), parent, project_id, description.
create_test_caseA
Create a new test case in TestCollab. Tip: Call get_project_context first to resolve suite/tag/custom field names to IDs.
Required: title Optional: project_id, suite (ID or title), description, priority (0=Low, 1=Normal, 2=High), steps, tags, requirements, custom_fields, attachments
Steps format: [{ "step": "action", "expected_result": "result" }]
Custom fields format: [{ "id": 5, "name": "field_name", "value": "value", "valueLabel": "display" }]
Example: { "title": "Verify login", "priority": 2, "steps": [ { "step": "Navigate to login", "expected_result": "Page loads" }, { "step": "Enter credentials", "expected_result": "Login succeeds" } ] }
Inputs: title (required), tags, steps, suite, +6 more.
create_test_planA
Create a test plan in TestCollab using a single MCP tool call.
Before calling this tool:
Ask follow-up questions for missing required information.
Do not infer or auto-generate required values like project_id.
Execution flow:
POST /testplans
POST /testplantestcases/bulkAdd (optional)
POST /testplanconfigurations (optional)
POST /testplans/assign (optional)
Optional:
project_id
title (defaults to "Test Plan DD Month YYYY HH:mm:ss" if omitted)
description
priority (0=Low, 1=Normal, 2=High)
test_plan_folder (ID or title)
release (ID or title)
start_date, end_date
custom_fields
test_cases (test_case_ids/selector/tag_id/tag_name/assignee; assignee supports user ID/"me"/name)
override_assignees (default false: keeps default case assignees, assigns only cases with none)
configurations
assignment (supports user IDs/"me"/names; if user says "assign to me", use "me")
Example: { "project_id": 16, "title": "Release 2.9 Regression", "priority": 1, "test_cases": { "test_case_ids": [101, 102, 103] }, "configurations": [ [{ "field": "Browser", "value": "Chrome" }, { "field": "OS", "value": "Windows" }] ], "assignment": { "executor": "team", "assignment_criteria": "testCase", "assignment_method": "automatic", "user_ids": [27, 31] } }
Inputs: title, release, end_date, priority, +9 more.
delete_suiteA
Delete a test suite from TestCollab.
WARNING: This will delete the suite and may affect child suites and test cases. Use with caution.
Required: id (suite ID) Optional: project_id
Inputs: id (required), project_id.
delete_test_planA
Delete a test plan from TestCollab.
WARNING: This permanently deletes the test plan and related execution data.
Required: id (test plan ID) Optional: project_id
Inputs: id (required), project_id.
get_project_contextA
Get project context including project name, description, application type, suite tree, tags, test_case_custom_fields, test_plan_custom_fields, requirements, test plan folders, releases, and project users. Returns the metadata needed to resolve human-readable names (e.g. suite titles, tag names, folder titles, release titles, user names) to numeric IDs used by other tools. Also returns the project description and app_type (web_app, mobile_app, api, desktop_app, other) which should inform the style of test steps you generate.
IMPORTANT: Call this tool at the start of every conversation before using any other TestCollab tool. This avoids errors from unresolved suite names, tag names, or custom field references.
Inputs: project_id.
get_suiteA
Get details of a specific test suite by ID. Returns the suite's title, description, parent_id, and other metadata.
Required: id (suite ID) Optional: project_id
Inputs: id (required), project_id.
get_test_caseA
Fetch a single test case with full details, including steps and expected results.
Required: id (test case ID) Optional: project_id, parse_reusable_steps (default: true)
Example: { "id": 1835, "parse_reusable_steps": true }
Inputs: id (required), project_id, parse_reusable_steps.
get_test_planA
Fetch a single test plan with summary details:
Included test cases count
Test plan configurations
Test plan runs
Current execution progress status
Required: id or title Optional: project_id, include_configurations, include_runs, runs_limit, runs_offset, runs_sort
Example: { "id": 812, "project_id": 16 }
or
{ "title": "Release 3.0 Regression", "project_id": 16 }
Inputs: id, title, runs_sort, project_id, +4 more.
get_test_plan_casesA
Get all cases in a plan with steps, expected results, linked datasets (parameters and indexed rows), active status system names and per-configuration status. Provide run_id to get the token owner's assigned execution IDs, revision steps, saved datasets and datasetResults row/step coordinates.
Inputs: test_plan_id (required), run_id, project_id.
list_suitesA
List all test suites in a TestCollab project as a hierarchical tree. Returns the complete suite tree with parent-child relationships.
Each suite node includes: id, title, parent_id, children (nested suites).
Optional filter:
title: Filter suites by title substring.
title_contains: Filter suites by title substring (applied at API level).
parent: Filter suites by parent suite ID.
description: Filter suites by description substring.
Inputs: title, parent, project_id, description, +2 more.
list_test_casesA
List test cases from a TestCollab project with optional filtering, sorting, and pagination. Tip: Call get_project_context first to resolve suite/tag/custom field names to IDs. Note: list_test_cases may omit full step details; use get_test_case for a complete test case with steps.
Filter fields include:
id, title, description, steps, priority (0=Low, 1=Normal, 2=High)
suite (ID or title), created_by, reviewer, poster (user IDs)
created_at, updated_at, last_run_on (dates)
tags, requirements (arrays of IDs or names)
under_review, is_automated (0 or 1)
run_count, avg_execution_time, failure_rate
Filter types:
text: equals, notEqual, contains, notContains, startsWith, endsWith, isBlank
number: equals, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, inRange
date: equals, notEqual, greaterThan, lessThan, inRange
Example filter: { "priority": { "filterType": "number", "type": "greaterThanOrEqual", "filter": 1 }, "title": { "filterType": "text", "type": "contains", "filter": "login" } }
Inputs: sort, limit, suite, filter, +2 more.
list_test_plansA
List test plans from a TestCollab project with optional filtering, sorting, and pagination.
Optional filters:
title_contains
status: 0/1/2/3 or draft/ready/finished/finished_with_failures
priority: 0/1/2 or low/normal/high
archived: true/false
created_by: creator user ID
test_plan_folder: folder ID or folder title
release: release ID or release title
created_at_from/to, updated_at_from/to, start_date_from/to, end_date_from/to, last_run_from/to
filter: raw filter object for advanced keys (merged with explicit filters)
Example: { "project_id": 16, "title_contains": "Release", "status": "ready", "priority": "high", "created_by": 27, "sort_by": "updated_at", "sort_order": "desc", "limit": 25, "offset": 0 }
Inputs: limit, filter, offset, status, +19 more.
move_suiteA
Move a test suite to a different parent suite, or to root level. Tip: Call get_project_context first to see the current suite tree.
Required: id (suite ID), parent (new parent ID, title, or null for root) Optional: project_id
Examples: Move under a parent: { "id": 10, "parent": "Authentication" } Move to root level: { "id": 10, "parent": null }
Inputs: id (required), parent (required), project_id.
reorder_suitesA
Set the sort order of sibling suites under a given parent. Tip: Call get_project_context or list_suites first to see current suite IDs and order.
Required: parent (parent suite ID, title, or null for root), suite_ids (ordered array of suite IDs) Optional: project_id
Example - reorder root-level suites: { "parent": null, "suite_ids": [5, 3, 8, 1] }
Example - reorder children of "Authentication": { "parent": "Authentication", "suite_ids": [12, 10, 15] }
Inputs: parent (required), suite_ids (required), project_id.
report_resultsA
Report a structured list of results for the caller's assigned executions in a plan. Defaults to the latest run; configuration_id selects matrix executions. Optionally set plan custom_fields and mark omitted assigned executions skipped after all supplied results succeed. Records MCP provenance; no report-file parsing, auto-create or builds.
Inputs: results (required), test_plan_id (required), run_id, project_id, +2 more.
report_test_case_resultA
Report one executed_test_case_id in a run, with a status system name (custom statuses supported), comment, additional time in milliseconds, step_results or dataset_results by dataset ID and zero-based row/step indexes. Up to 10 attachments across the call, including step and row files. file_path: stdio only, 10 MB/file. file_name plus content_base64: 1 MB decoded/file. The API token determines the executor.
Inputs: run_id (required), status (required), executed_test_case_id (required), comment, +5 more.
update_suiteA
Update an existing test suite in TestCollab. Only provided fields will be updated.
Required: id (suite ID) Optional: project_id, title, description
Note: To move a suite to a different parent, use the move_suite tool instead.
Example: { "id": 42, "title": "Renamed Suite", "description": "Updated description" }
Inputs: id (required), title, project_id, description.
update_test_caseA
Update an existing test case in TestCollab. Only provided fields will be updated. Tip: Call get_project_context first to resolve suite/tag/custom field names to IDs. Tip: If you need existing steps (e.g., to fill missing expected results), call get_test_case first and then use steps_patch.
Required: id (test case ID)
Optional fields:
title: New title
suite: Move to different suite
description: New description (HTML)
priority: 0 (Low), 1 (Normal), 2 (High)
steps: Replaces all existing steps
steps_patch: Patch steps by step number (1-based) without replacing all steps
tags: Replaces all existing tags
requirements: Replaces all existing requirements
custom_fields: Update specific custom fields
Example: { "id": 1712, "title": "Updated login test", "priority": 2 }
Example - patch a single step: { "id": 1714, "steps_patch": [ { "step_number": 1, "expected_result": "Appropriate expected result" } ] }
Inputs: id (required), tags, steps, suite, +8 more.
update_test_planA
Update an existing test plan in TestCollab.
Required:
id (test plan ID)
All other fields are optional and only provided fields are updated.
Fields:
title
description (null to clear)
priority: 0/1/2 or low/normal/high
status: 0/1/2/3 or draft/ready/finished/finished_with_failures
test_plan_folder: ID/title/null
release: ID/title/null
start_date, end_date (null to clear)
archived
custom_fields (null/[] to clear)
assignee (single-user convenience)
assignment (advanced assignment payload)
Example: { "id": 812, "title": "Release 3.0 Regression", "status": "ready", "test_plan_folder": "Mobile", "assignee": "me" }
Inputs: id (required), title, status, release, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools have clearly distinct resource/action targets, such as suite CRUD versus plan CRUD versus case read/write. The main ambiguity is between report_test_case_result and report_results, which both report execution results but at different granularity; descriptions help, though an agent could still hesitate between them.
Tool names consistently use snake_case with a verb_noun pattern: get_test_case, create_test_plan, update_suite, delete_suite, move_suite, reorder_suites, report_results, and get_project_context. Singular/plural variation follows the operation (get_suite vs list_suites), which is predictable and readable.
Twenty tools is somewhat heavy but reasonable for a test-management surface spanning cases, plans, suites, execution reporting, and project context. Each tool broadly earns its place, though the two reporting tools add some redundancy.
Suite lifecycle coverage is strong, and plans and cases have substantial create/read/update coverage. However, test cases lack a delete operation, and there is no clear tool for adding or removing cases from an existing plan after creation, which are notable lifecycle gaps.
Maintenance
Related MCP Connectors
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Test management for AI agents: cases, runs, results, cycles and traceability.
Write, run and check natural-language browser tests of your web app from your AI assistant.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with TestRail test management systems through comprehensive API integration. Supports retrieving and updating test cases, projects, suites, runs, and results, plus adding attachments and managing test data through natural language commands.1829 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Testmo test management platform for creating, reading, updating, and deleting test cases, managing folders, and organizing test runs through natural language.4MIT
- AlicenseAqualityCmaintenanceConnect your AI coding assistant to TestRail to manage test cases, runs, results, and more directly from VS Code, Cursor, Claude Desktop, or Claude Code.522 npm1MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with TestRail test management system, supporting full CRUD operations on projects, suites, sections, test cases, runs, results, plans, and milestones.35327 npm1MIT