Skip to main content
Glama
TestCollab MCP Server

TestCollab MCP Server

by TCSoftInc

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-server

Or 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 start

Related MCP server: Testmo MCP Server

Available Tools

list_test_cases

List test cases from a project with optional filtering.

Parameters:

Name

Type

Required

Description

project_id

number

No*

Project ID (*required if TC_DEFAULT_PROJECT not set)

suite

number|string

No

Filter by suite ID or title

filter

object

No

Filter conditions

sort

array

No

Sort specification

limit

number

No

Max results (1-100, default: 50)

offset

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

TC_API_TOKEN

Yes

—

API token from your TestCollab profile

TC_API_URL

No

https://api.testcollab.io

TestCollab API base URL

TC_DEFAULT_PROJECT

No

—

Default project ID (makes project_id optional in every tool call)

EU region: If your TestCollab account is hosted in the EU, use https://api-eu.testcollab.io as your TC_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 title, parent, and description filters)

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 build

Then 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         # Lint

Troubleshooting

Server not appearing in your client

  • Restart the client after adding the config

  • Verify Node.js 20+ is installed: node --version

  • Test 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_URL points to the correct server

"project_id is required" error

  • Set TC_DEFAULT_PROJECT in your env config, or

  • Specify the project in your prompt: "Show me test cases in project 16"

License

MIT

Available Tools

20 tools
create_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:

  1. POST /testplans

  2. POST /testplantestcases/bulkAdd (optional)

  3. POST /testplanconfigurations (optional)

  4. 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

    A3.9/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      18
      29 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connect your AI coding assistant to TestRail to manage test cases, runs, results, and more directly from VS Code, Cursor, Claude Desktop, or Claude Code.
      5
      22 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with TestRail test management system, supporting full CRUD operations on projects, suites, sections, test cases, runs, results, plans, and milestones.
      35
      327 npm
      1
      MIT