Testcollab MCP Server

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

Available Tools

list_test_cases

List test cases from a project with optional filtering.

Parameters:

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

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

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