# testcatalyst-mcp > MCP server for TestCatalyst — lets Claude run browser tests with full visibility in TestCatalyst Latest version **1.27.0** (published 2026-09-04) · 0 weekly downloads ## Install ```sh npm install testcatalyst-mcp pnpm add testcatalyst-mcp yarn add testcatalyst-mcp bun add testcatalyst-mcp ``` Provides the command `testcatalyst-mcp`. ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types. ## Facts | | | |---|---| | Version | 1.27.0 | | Published | 2026-09-04 | | First published | 2026-06-26 | | Weekly downloads | 0 | | TypeScript types | none | | Module format | ESM | | Node | >=18 | | Dependencies | 2 | | Unpacked size | 106.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | horbarz | ## Links - npm: https://www.npmjs.com/package/testcatalyst-mcp - npm.io page: https://npm.io/package/testcatalyst-mcp ## Dependencies (2) - [undici](https://npm.io/package/undici.md) ^7.28.0 - [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.12.1 ## Recent versions - 1.27.0 (latest) — 2026-09-04 - 1.26.0 — 2026-09-03 - 1.25.0 — 2026-08-29 - 1.24.0 — 2026-08-25 - 1.23.0 — 2026-07-31 - 1.22.0 — 2026-07-30 - 1.20.0 — 2026-07-30 - 1.19.0 — 2026-07-27 - 1.17.0 — 2026-07-24 - 1.14.0 — 2026-07-23 - 1.13.0 — 2026-07-21 - 1.12.0 — 2026-07-14 - 1.11.0 — 2026-07-14 - 1.10.0 — 2026-07-09 - 1.9.1 — 2026-07-09 - … 11 more at https://npm.io/package/testcatalyst-mcp/versions ## README # 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: ```json { "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. ### On a corporate network? 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](https://www.npmjs.com/package/chrome-devtools-mcp)** (recommended) — add to your MCP client config: ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["chrome-devtools-mcp@latest"] } } } ``` - **[Playwright MCP](https://www.npmjs.com/package/@playwright/mcp)**: ```json { "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 ```bash 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. --- _Source: https://npm.io/package/testcatalyst-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._