TestCatalyst MCP Server

Lets Claude run browser tests and stream every step, screenshot, and bug report directly into TestCatalyst — with a live view you can watch in real time.

1. Get your MCP token

1. Open TestCatalyst and go to Settings → MCP.
2. Click Generate Token (or copy an existing one).
3. Keep this token — you'll paste it into your Claude Desktop config below.

2. Add to Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS, and add the following inside the "mcpServers" object:

{
  "mcpServers": {
    "testcatalyst": {
      "command": "npx",
      "args": ["-y", "testcatalyst-mcp"],
      "env": {
        "TC_API_URL": "https://testcatalyst.co",
        "TC_TOKEN": "your-mcp-token-here"
      }
    }
  }
}

• TC_API_URL — The base URL where your TestCatalyst app is running. Use https://testcatalyst.co for the hosted app, or http://localhost:3000 if you're running TestCatalyst locally.
• TC_TOKEN — The MCP token you copied from Settings → MCP.

Restart Claude Desktop after saving.

3. Browser automation (required for web-based tests)

TestCatalyst MCP tracks and reports test runs, but it doesn't drive a browser itself. For any test that navigates a real web page, Claude also needs one of the following connected:

• Chrome DevTools MCP (recommended) — add to your MCP client config:

  {
    "mcpServers": {
      "chrome-devtools": { "command": "npx", "args": ["chrome-devtools-mcp@latest"] }
    }
  }

• Playwright MCP:

  {
    "mcpServers": {
      "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
    }
  }

• Claude in Chrome browser extension — install from the Chrome Web Store and make sure it shows as connected before starting a run.

Claude should check for one of these before calling tc_start_run, and if none is connected, tell you which one to install (with the exact command above) instead of failing partway through a run.

4. The 24 tools

| Tool | When Claude uses it | |---|---| | tc_list_projects | At the start, to find which project to attach the run to | | tc_get_jira_issue | To pull a Jira ticket's summary, acceptance criteria, status, and figmaLink — no separate Atlassian MCP needed — before calling tc_ensure_suite/tc_start_run | | tc_get_project_context | Before testing, to see existing test cases and recent bugs so work isn't duplicated | | tc_ensure_suite | Before tc_start_run, to find-or-create the test suite. Idempotent by Jira issue key if you have one (most reliable), or by suite name otherwise — pass the same suite name/Jira key on a re-run so retest results update the existing test cases instead of creating a duplicate suite | | tc_get_test_cases | Before tc_start_run, to fetch the exact test cases already registered for a project (optionally filtered by Jira issue key or suite ID) so you know precisely what to execute | | tc_start_run | Before opening the browser — creates the run in TestCatalyst and returns a live-view URL. Requires a connected browser-automation tool (see above) for web-based tests | | tc_report_step | After every single action (click, fill, assert) — streams progress in real time. For HTTP/API steps, pass the http*/response* fields instead of a screenshot — TestCatalyst renders a request/response snapshot automatically, and a failed API step gets a "Test it manually" button that opens the exact request in the API Runner. For screenshots, prefer screenshotPath (a local file path) over screenshot (inline base64) — see note below | | tc_create_bug | Whenever an assertion fails or unexpected behavior is observed. Mention the TC-XXX ID if the bug is about a specific test case — it gets linked and auto-marked Resolved once that test case passes on a later re-run. Bugs are grouped into a bug sheet per suite/ticket, not one shared sheet. Same screenshotPath/screenshot choice as tc_report_step | | tc_attach_bug_screenshot | To add a screenshot to a bug after it's already been created (e.g. evidence wasn't ready yet, or you want to add a second one) — pass the same runId plus the bug_id from tc_create_bug (both are needed since bug numbering restarts per ticket's sheet). Same screenshotPath/screenshot choice | | tc_get_run | To check current run status or revisit earlier steps | | tc_save_script | After a run passes, to save the Playwright script that reproduces the steps you just executed — stored under the run's project/suite and can be pushed to CI from the TestCatalyst UI | | tc_finish_run | After all steps are complete — marks the run passed/failed/stopped and generates the report | | tc_upload_recording | Before finishing (if you have a screen recording and the user agreed to saving it) — shows up on the run page and in CATS. Prefer videoPath over inline video — see note below | | tc_post_jira_comment | To share results directly on the Jira ticket — e.g. the run summary or a link to the report | | tc_list_figma_frames | When you only have a general Figma file link (e.g. auto-detected from a Jira ticket via tc_get_jira_issue's figmaLink field) rather than a link to one specific frame — lists all frame names so you can pick the one matching the page you're testing | | tc_get_figma_design | When comparing a page against its Figma design — fetches a rendered image of a specific frame (the link must contain node-id=..., or use a figmaUrl returned by tc_list_figma_frames) to compare against a screenshot you take of the live page. Requires a Figma personal access token connected in Settings → Integrations | | tc_check_figma_fields | When verifying an API's field names match the design spec, rather than a visual check — extracts field/label names from a Figma frame and diffs them against field names you've observed in an API request/response | | tc_list_postman_collections | When testing an API and the user already has it in Postman — lists collections from the workspace's connected Postman account so you can pick the right one by name. Requires a Postman API key connected in Settings → Integrations | | tc_get_postman_collection | After picking a collectionUid from tc_list_postman_collections — fetches its requests (method, url, headers, body) and collection variables, so you can drive API test steps without asking the user to describe each endpoint | | tc_list_skills | Before ad-hoc testing work — lists the workspace's testing playbooks: TestCatalyst's built-in Test Architect skills (test design, ATDD, automation, test review, NFR audits, traceability/gate) plus any custom ones the team has authored | | tc_get_skill | After picking an id from tc_list_skills — fetches the full markdown instructions to follow as your playbook | | tc_create_skill | To save a reusable playbook you've developed so teammates can reuse it. Idempotent by name — reusing an existing name returns it unchanged instead of duplicating. If content came out wrong, use tc_update_skill instead of re-calling this | | tc_update_skill | To fix a custom skill's name/description/instructions after the fact (e.g. broken content from a bad substitution). Only the fields you pass are changed. Errors on system skills | | tc_delete_skill | To permanently remove a custom skill (e.g. one saved with broken or duplicate content). Errors on system skills |

A note on screenshots and recordings: most browser-automation MCP tools only let Claude see a captured screenshot (or a saved-file confirmation), not copy its raw bytes into another tool call — so trying to hand-construct base64 image/video data is unreliable. If your browser tool can save to a local file (e.g. chrome-devtools-mcp's take_screenshot with a filePath argument, or Playwright's built-in video recording), pass that path via screenshotPath / videoPath instead — TestCatalyst MCP reads the file and encodes it for you. Use screenshot / video only when your tool already hands back an inline base64 data URL.

5. Sample prompt

Give Claude a prompt like this to kick off a full test session:

Use TestCatalyst to test the login flow on http://localhost:3000.

1. List my TestCatalyst projects and pick the most relevant one (or ask me).
2. Check the project context for existing test cases and recent bugs so you don't duplicate work.
3. Start a TestCatalyst run before opening the browser.
4. Navigate to the login page.
5. Try logging in with valid credentials — report each step.
6. Try logging in with invalid credentials and assert the error message appears — report each step.
7. Take a screenshot after each key assertion and attach it to the step.
8. If anything fails, create a bug report with steps to reproduce.
9. Finish the run with a summary of what passed and what failed.

Claude will call the TestCatalyst tools automatically, and you'll see a live feed of steps and screenshots inside TestCatalyst while the test runs.

6. Local development

cd mcp
npm install
TC_API_URL=http://localhost:3000 TC_TOKEN=your-token node index.mjs

The server speaks MCP over stdio — Claude Desktop (or any MCP host) spawns and communicates with it automatically.