tcm-mcp
This server gives AI agents a stable MCP tool interface for reading and writing TCM test cases without direct DB access.
Project & suite discovery:
list_projects,search_suite,list_suites(scope by project UUID or name).Suite creation:
create_suite(immediate commit, no dry-run).Test-case listing:
list_test_cases— filter by project, suite, search term, or tags; 50 default / 200 max.Test-case detail:
get_test_caseby display_id (e.g. APA-3), including steps.Test-case creation:
create_test_casewith steps, priority, tags, platform_tags, automation_status; requires dry-run → human approval → commit.Test-case updates:
update_test_casepartial field updates; steps are full-replace; same dry-run/approval flow.Read safety: trashed/soft-deleted cases are excluded.
Auth options: refreshing login session, legacy static JWT, or Clutch API key for headless/agent write attribution.
Zero-config default: points at production TCM by default; login tool available before auth.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tcm-mcp Get details for test case APA-3"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tcm-mcp — TCM MCP Server (Epic 1: Test Case CRUD)
A stdio MCP server that gives AI agents (Torque, triage-e2e, Claude agents) a stable tool interface to read and write TCM test cases — without touching the database schema directly.
It is a thin client: every tool call proxies a TCM REST endpoint. ID resolution, validation, display_id generation, the in_cicd lock, and soft-delete scoping all happen inside TCM. Agents reference cases by display_id (e.g. APA-3); internal UUIDs are never exposed.
Full design: docs/features/mcp-e1-test-case-crud.md (in the main TCM repo).
Tools
Tool | Purpose |
| Discover the projects you can see ( |
| Resolve a suite name/prefix → |
| List every suite in a project — each with |
| Create a suite in a project and return its |
| Lightweight filterable list ( |
| Full detail + steps, by |
| Create a case with steps — dry-run → approval → commit (see below). |
| Partial update; steps are full-replace when provided — same dry-run flow. |
Reads exclude trashed (soft-deleted) cases. Test-case writes (create_test_case, update_test_case) require the dry-run flow. create_suite is the one exception — it commits on the first call, because a suite is an empty container with nothing to diff and no destructive edit to preview.
Project scoping. search_suite, list_suites, and list_test_cases scope by project. Pass a project_id (UUID) directly, or a project_name — the server resolves the name to an id via list_projects (case-insensitive exact match; an unknown name returns NOT_FOUND and an ambiguous one returns AMBIGUOUS with the candidate ids). Use list_projects first to discover ids. list_test_cases with no project returns cases across every project you can see.
Tag filtering. list_test_cases takes a tags array — { "tags": ["needs-qa-review", "imported-from-dev-tests"] } returns cases carrying any of them (case-insensitive), each with its full tags list. TCM filters in the database across the whole project, so total is the real match count. Tags are stored canonically (trimmed, lowercased, de-duplicated), so Smoke and smoke are one tag.
Related MCP server: kiwi-tcms-mcp
Requirements
Node.js ≥ 18 (for
npxand the globalfetch).Git read access to
JoinFullStackDev/tcm-mcp— the package is distributed by git URL, not published to npm. On headless hosts (OpenClaw/Torque) a git token must be present in the environment.That's it for the TCM URL: it defaults to production (
https://tcm-ochre.vercel.app), so there's nothing to look up or set. You just need to authenticate (Quickstart).
Because it's distributed by git URL, npx clones the repo and builds from source on first run (via the package's prepare → tsc step), so the first launch is slower. Subsequent runs are cached.
Quickstart
Zero-config: the production TCM instance (https://tcm-ochre.vercel.app) is baked in as the default, so you never set TCM_BASE_URL. Point at a different instance only if you self-host (see Environment variables).
Prerequisite — git access. This package is fetched by git URL from a private repo, so the machine running it needs git read access (gh auth login, or a git token for headless hosts). Node ≥ 18 must be installed. On macOS, GUI-launched Claude Desktop may not see your shell PATH — if the server fails to start, use an absolute path to npx in the config (find it with which npx).
1. Register the server
Claude Code — one command, nothing to edit by hand:
claude mcp add tcm --scope user -- npx --yes github:JoinFullStackDev/tcm-mcp#v1.7.0 --stdio--scope user makes it available in every project. (Drop it to scope to the current project; Claude Code writes the .mcp.json for you.)
Claude Desktop — no CLI, so add it to the config file once:
Settings → Developer → Edit Config — this creates and opens
claude_desktop_config.jsonfor you (no folder to make yourself):macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the
tcmentry (merge intomcpServersif it already exists), then fully quit + reopen Claude Desktop:
{
"mcpServers": {
"tcm": {
"command": "npx",
"args": ["--yes", "github:JoinFullStackDev/tcm-mcp#v1.7.0", "--stdio"]
}
}
}Pin to a tag (
#v1.7.0), not a branch — a branch ref re-resolves on every launch and can trip the 30 s MCP startup timeout. Noenvblock is needed.
2. Sign in
The server starts even before you've logged in — it just exposes a login tool. So the easiest way (works in Claude Desktop and Claude Code, no terminal):
Just ask Claude: "Log me into TCM."
Claude calls the login tool, a browser opens once for Google sign-in, and the server stores a session it then keeps refreshed. The other tools light up immediately after. (Playwright is auto-installed on first login — a one-time ~100 MB browser download into ~/.tcm-mcp.)
Prefer a terminal? Same thing, run once:
npx --yes github:JoinFullStackDev/tcm-mcp#v1.7.0 loginDetails: Auto-refreshing login.
If you'd rather edit .mcp.json directly (Claude Code project or ~/.claude/.mcp.json), the minimal entry is just command + args as shown above. To use the legacy static-token mode instead of a login session (e.g. CI that already has a JWT), add an env block — note it expires ~1h and refreshing it needs a full client restart:
{
"mcpServers": {
"tcm": {
"command": "npx",
"args": ["--yes", "github:JoinFullStackDev/tcm-mcp#v1.7.0", "--stdio"],
"env": { "TCM_USER_TOKEN": "${TCM_USER_TOKEN}" },
},
},
}Auth modes
The server resolves its mode at startup. Precedence: CLUTCH_API_KEY → login session file → TCM_USER_TOKEN.
Mode | Selected by | Sends | Use for | Attribution |
Refreshing token (interactive) | a session file ( |
| Claude Code, human in the loop | The real user (their Supabase session) |
Static token (legacy) |
|
| CI / scripts injecting a JWT | The real user (their Supabase JWT) |
Clutch key (headless) |
|
| Torque via Clutch/OpenClaw | The service profile — see |
In refreshing mode the server auto-renews the access token before expiry and again on any 401 (retrying the request once), and persists the rotated refresh token back to the session file. In static and clutch modes a 401 is terminal (nothing to refresh).
In headless mode you must also set MCP_AGENT_USER_ID, or create/update will fail on the created_by/updated_by NOT NULL constraint. The server prints a startup warning if it's missing. When set, the server forwards it to TCM as an X-Agent-User-Id header (trusted only alongside a valid X-Clutch-Key), so each agent attributes its own writes; TCM falls back to its own MCP_AGENT_USER_ID env if the header is absent. (Requires TCM with the matching write-attribution support.)
Auto-refreshing login (recommended)
The login helper signs you into TCM in a browser once and writes a session file the server then uses to keep itself authenticated indefinitely — no ~1h token churn, no client restarts.
# no clone needed — runs straight from the git URL:
npx --yes github:JoinFullStackDev/tcm-mcp#v1.7.0 login
# ...or, from a local clone of this repo:
npm run loginOpens a browser only if there's no valid saved session; later runs refresh silently (headless, no window).
Playwright is installed for you on first login. It is deliberately not a server dependency (keeps
npx <server>installs lean ~50 MB), so the login helper installsplaywright+ Chromium once into~/.tcm-mcp(a ~100 MB one-time download) if they aren't already present. You do not need a separate "Playwright MCP" — the login is fully self-contained.
It writes ~/.tcm-mcp/session.json (mode 0600) containing the Supabase project URL, anon key (public), and the access + refresh tokens. From then on the MCP server (mode “refreshing token”) mints fresh access tokens on demand.
Session file location:
~/.tcm-mcp/session.json, override withTCM_SESSION_FILE.Browser profile:
~/.tcm-mcp/browser, override withTCM_BROWSER_PROFILE.Security: the refresh token is a long-lived credential — the file is
0600and must never be committed or shared. Supabase rotates the refresh token on every refresh; the server persists the new one atomically.When it expires: if the refresh token is ever revoked/expired, tool calls fail with a clear “run
npm run login” message. Re-run the helper.Anon key capture: the helper sniffs the public
apikeyheader from Supabase network traffic. If capture ever fails, setSUPABASE_ANON_KEY(safe to expose) and re-run.
Environment variables
Variable | Required | Mode | Purpose |
| no (defaults to production) | all | Base URL of the TCM instance. Defaults to |
| no | refreshing | Override the session-file path (default |
| no | refreshing | Override the login browser-profile dir (default |
| one credential | static | User's Supabase JWT (legacy; expires ~1h, no refresh). |
| one credential | headless | Server-to-server key; must match TCM's |
| yes, in headless mode for writes | headless |
|
The recommended credential is the login session file (npm run login), not TCM_USER_TOKEN — see Auto-refreshing login. TCM_USER_TOKEN remains for CI / scripts that already have a JWT.
The write safety flow (dry-run → approval → commit)
create_test_case and update_test_case are two-pass:
Call with
dry_run: truefirst. The tool validates, resolves IDs, and returns a summary (create: the proposed case; update: a field-level diff + before/after steps). No write happens.A human reviews and approves — Torque relays the summary to Slack via Clutch; Claude Code shows it inline in the chat.
Call again with
dry_run: false(or omitdry_run) to commit.
The server does not technically enforce that a dry-run/approval happened before a commit (decided: PRD OQ-4 Option A) — it's a process convention. Don't call with dry_run: false without human approval.
Local development
git clone https://github.com/JoinFullStackDev/tcm-mcp && cd tcm-mcp
npm install # runs prepare → tsc → dist/
npm run build # rebuild after changes
# run the stdio server directly (Ctrl-D / EOF to exit)
TCM_BASE_URL=https://your-tcm-instance.example.com \
TCM_USER_TOKEN=your-jwt \
node dist/index.js
npm run dev # same, via ts-node (no build step)Startup logs (mode, base URL, "Ready") are written to stderr, so they don't interfere with the stdio MCP protocol on stdout.
Notes & caveats
Audit logging (
mcp_tool_calls, PRD Appendix C) requires migration00042applied to the TCM database. The log inserts are fire-and-forget and non-blocking — if the table is missing, tools still work; only the audit trail is skipped.Distribution is git-URL only (no npm publish). Pin a tag; ensure hosts have git access.
The
--stdioarg in the config is cosmetic — stdio is the only transport.
Available Tools
5 toolscreate_test_caseA
Create a test case with steps. REQUIRED: call with dry_run: true first. Review the summary with a human. Only call with dry_run: false (or omit dry_run) after explicit human approval. Steps are required. display_id is assigned by TCM on commit.
Inputs: steps (required), title (required), suite_id (required), tags, +6 more.
get_test_caseA
Get full detail of a test case by display_id (e.g. "APA-3"), including all steps. Use this before update_test_case to review the current state.
Inputs: display_id (required).
list_test_casesA
List test cases with lightweight projection (display_id, title, automation_status, priority). Filterable by project, suite, or search term. Default limit 50, max 200.
Inputs: limit, search, suite_id, project_id.
search_suiteA
Resolve a suite name or prefix to a suite reference. Call this before create_test_case or list_test_cases to get the suite_id. Returns all matches so the caller can disambiguate if >1.
Inputs: project_id (required), name_or_prefix (required).
update_test_caseA
Partially update an existing test case by display_id. If steps is provided, ALL existing steps are wiped and replaced (full-replace — not partial). REQUIRED: call with dry_run: true first. The dry-run shows the full before/after diff including steps. Only call with dry_run: false after explicit human approval.
Inputs: display_id (required), tags, steps, title, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose: create, update, get, list, and suite search. No two tools overlap in function, and search_suite clearly serves as a helper for resolving suite IDs before other operations.
All tools use a verb_noun snake_case pattern (create_, update_, get_, list_, search_). The only deviation is list_test_cases using plural while others use singular, which is a standard convention for list operations.
Five tools is well-scoped for a test case management server. Each tool covers a necessary operation without redundancy or bloat.
Core CRUD operations are present (create, get, update, list), but delete_test_case is missing. Suite management is limited to search, with no create/update/delete for suites, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for TestRail that enables AI assistants to interact with TestRail's test management platform. It can query and manage projects, test cases, runs, results, plans, milestones, and more.MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that exposes Kiwi TCMS as a set of AI-callable tools, enabling assistants to create and manage test plans, test cases, test runs, and executions directly from a conversation.1-
- FlicenseNot gradedqualityCmaintenanceMCP server that enables AI agents to programmatically run tests, query results, and receive intelligent recommendations about test execution strategy.-
- AlicenseAqualityCmaintenanceMCP server for managing test cases, cycles, and results in Zephyr Scale on self-hosted Jira. Enables AI agents to create, search, update, and delete test artifacts through natural language.4156 npmMIT