1.27.0 • Published 1 month agoCLI

testcatalyst-mcp

Licence

—

Version

1.27.0

Deps

Size

106 kB

Vulns

Weekly

Summary Dependency Versions

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

Open TestCatalyst and go to Settings → MCP.
Click Generate Token (or copy an existing one).
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.

If tool calls fail with a connection timeout but work fine elsewhere, your network likely requires a proxy for outbound traffic. Add HTTPS_PROXY (or HTTP_PROXY) to the same env block above with your proxy's URL, e.g. "HTTPS_PROXY": "http://proxy.company.com:8080" — the server picks this up automatically. NO_PROXY is also respected if you need to exclude specific hosts.

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 28 tools

Tool	When Claude uses it
`tc_list_projects`	At the start, to find which project to attach the run to
`tc_select_skills`	Once at the start of every session, before `tc_ensure_suite` or `tc_start_run` — asks the user which testing skill(s)/playbook(s) should guide the session (multiple, or none). Both of those tools error and point back here if you skip it. Always returns the skill list for Claude to relay in a normal chat message (never an interactive picker) and call again with the user's answer
`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_get_open_bugs`	At the start of a retest pass — fetches open (not Resolved/Closed) bugs for a project, optionally narrowed by suiteId or a specific test case's tcId, with full repro steps so you can retest without digging up the original report. Prefer this over `tc_get_project_context`'s small unfiltered bug sample when the goal is retesting
`tc_ensure_suite`	Before `tc_start_run`, to find-or-create the test suite. Requires `tc_select_skills` to have run first this session. 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 `tc_select_skills` to have run first this session, and 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_update_bug_status`	After retesting a previously-filed bug, to record whether it's fixed (`Resolved`) or still broken (`Open`/`Reopened`, with a note). Pass the current run's `runId` (started against the same suite the bug belongs to) plus the `bugId` from `tc_get_open_bugs` — resolved via the run's suite, not the run that originally filed it, so this works retesting days later in a fresh run. Not needed if the linked test case just passes on its own during `tc_finish_run` — that already auto-resolves it
`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_set_automation_status`	To explicitly mark or unmark test cases as automated, independent of saving a script — e.g. correcting status after deleting a script, or marking cases covered by a pre-existing external suite
`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 frame names so you can pick the one matching the page you're testing. Includes frames nested a few levels deep (e.g. a modal/overlay and its steps), each with a `parentPath` breadcrumb so a wizard step isn't confused with the background frame it overlays
`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.