Connect TestCollab MCP Server to AI Assistants

Why use TestCollab MCP Server?

The MCP server lets your AI coding assistant interact directly with TestCollab:

• Create test cases using natural language

• Query existing test cases

• Update test cases when code changes

---

Supported AI Assistants

• Claude Code / Claude Desktop - Anthropic

• Cursor - AI-first code editor

• Windsurf - Codeium AI IDE

• Codex CLI - OpenAI

---

Step 1: Get Your API Token

1. Log in to TestCollab

2. Click profile avatar in the top-right

3. Select My Profile Settings

4. Go to API Token tab

5. Click Generate new API token

6. Copy and store securely

---

Step 2: Find Your Project ID

The Project ID is the number in your URL: testcollab.io/project/16/manage

---

Step 3: Configure Your AI Assistant

The MCP server runs locally via npx. No hosted server needed.

TC_API_TOKEN is required. Desktop apps opened from the Dock, Start menu, or an app launcher may not inherit variables from your shell, so use the user-level configuration file named for each client below. Replace PASTE_YOUR_TESTCOLLAB_TOKEN_HERE only in that local file. Never put a token in project-level MCP configuration, source control, screenshots, shell history, or support messages.

These user-level files can contain the token in plain text. Restrict each file to your operating system account and follow your organisation's secret-storage policy. On macOS or Linux, you can make a configuration file owner-only with chmod 600 path/to/config-file.

Claude Code

First load TC_API_TOKEN into the current terminal from your approved secret manager. Then run this command; the token value is expanded from the variable instead of appearing literally in the command:

claude mcp add testcollab \
  -e TC_API_TOKEN="${TC_API_TOKEN}" \
  -e TC_API_URL=https://api.testcollab.io \
  -e TC_DEFAULT_PROJECT=16 \
  -- npx -y @testcollab/mcp-server

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "PASTE_YOUR_TESTCOLLAB_TOKEN_HERE",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Claude Desktop starts the server in its own process, so the token must be present in this user-level env object. Fully quit and reopen Claude Desktop after saving the file.

Cursor

Add the server to Cursor's global, user-level MCP file: ~/.cursor/mcp.json on macOS or Linux, or %USERPROFILE%\.cursor\mcp.json on Windows. Do not put the token in a project's .cursor/mcp.json file.

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "PASTE_YOUR_TESTCOLLAB_TOKEN_HERE",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Save the file, fully quit Cursor, and reopen it.

Codex

Add the server to ~/.codex/config.toml. Codex desktop, the Codex CLI, and the IDE extension share this user-level configuration.

[mcp_servers.testcollab]
command = "npx"
args = ["-y", "@testcollab/mcp-server"]

[mcp_servers.testcollab.env]
TC_API_TOKEN = "PASTE_YOUR_TESTCOLLAB_TOKEN_HERE"
TC_API_URL = "https://api.testcollab.io"
TC_DEFAULT_PROJECT = "16"

If your operating system or secret manager injects TC_API_TOKEN into the Codex app process, omit the static TC_API_TOKEN line above and add env_vars = ["TC_API_TOKEN"] under [mcp_servers.testcollab] instead. Restart Codex after changing the configuration.

Windsurf

Add the server to ~/.codeium/windsurf/mcp_config.json on macOS or Linux, or %USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows:

{
  "mcpServers": {
    "testcollab": {
      "command": "npx",
      "args": ["-y", "@testcollab/mcp-server"],
      "env": {
        "TC_API_TOKEN": "PASTE_YOUR_TESTCOLLAB_TOKEN_HERE",
        "TC_API_URL": "https://api.testcollab.io",
        "TC_DEFAULT_PROJECT": "16"
      }
    }
  }
}

Save the file, fully quit Windsurf, and reopen it.

Self-Host Option

Clone from GitHub, run npm install and npm run build, then point your MCP client to node dist/index.js with the environment variables above.

---

Configuration Reference

EU region: If your TestCollab account is hosted in the EU, use https://api-eu.testcollab.io as your TC_API_URL.

---

Available Tools

---

Example Prompts

• "Create a test case for user login with valid credentials"

• "Show me all high priority test cases"

• "Update test case 1502 with new expected results"

• "List all test plans created this week"

• "Create a regression test plan with all test cases tagged 'smoke'"

---

Troubleshooting

Server not appearing: Restart your AI client after adding the config. Verify Node.js 20+ is installed.

401 Unauthorized: Check your API token is valid and not expired.

"project_id is required": Set TC_DEFAULT_PROJECT in your env config, or specify the project in your prompt.

Test manually: After loading TC_API_TOKEN from a secure source, run npx @testcollab/mcp-server to verify the server starts.

---

Resources

• GitHub Repository

• npm Package

• Model Context Protocol

• TestCollab API Docs