kiwi-tcms-mcp
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., "@kiwi-tcms-mcp List the test plans for product 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.
kiwi-tcms-mcp
A Model Context Protocol server for Kiwi TCMS. It exposes your Kiwi test-management data to any MCP client — Claude Code, Claude Desktop, Cursor, Cline, Zed, Continue, or your own — so you can browse and create test cases, build test plans and runs, and record execution results from a chat prompt.
49 tools over Kiwi's JSON-RPC API — products, versions, builds, categories, components, tags, test plans, cases, runs, executions — plus a raw
kiwi_rpcescape hatch for anything without a dedicated tool.Runs locally over stdio, authenticates with your own Kiwi username + password. Nothing is hosted, no shared credentials. You get exactly the permissions your Kiwi account has.
No build step — plain Node ESM,
node src/index.js.
MCP client ──MCP (stdio)──▶ kiwi-tcms-mcp ──HTTPS JSON-RPC──▶ Kiwi TCMSComing from TestRail? See the tool map — the surface mirrors the
@uarlouski/testrail-mcp-server MCP so a migration is mostly renaming fields.
Example prompts
"List the test plans for product 3 in Kiwi."
"Create a test case under category 12: title 'Login rejects expired token', priority P1, with steps and expected result."
"Mark cases 4001–4010 in run 87 as PASSED with the comment 'regression clean on build 2.3.1'."
"Show the execution history for test execution 55."
Setup
New here? Follow SETUP.md — step-by-step, cross-platform, plain language.
Quick version:
git clone https://github.com/ShahjahanAliTaimoor/kiwi-tcms-mcp.git
cd kiwi-tcms-mcp
npm installWire it into your MCP client
Every MCP client takes the same three things — a command, its args, and an env block.
Point it at src/index.js with your own Kiwi login:
{
"command": "node",
"args": ["/absolute/path/to/kiwi-tcms-mcp/src/index.js"],
"env": {
"KIWI_URL": "https://kiwi.example.com",
"KIWI_USERNAME": "<your kiwi login>",
"KIWI_PASSWORD": "<your kiwi password>"
}
}Claude Code — put it under the top-level
"mcpServers"in~/.claude.json(C:\Users\<you>\.claude.jsonon Windows), or runclaude mcp add.Claude Desktop —
mcpServersinclaude_desktop_config.json(%APPDATA%\Claude\on Windows,~/Library/Application Support/Claude/on macOS); use an absolute path tonode.Cursor / Cline / Continue / Zed — their MCP settings use the same
command/args/envshape.
Restart the client. Tools show up namespaced, e.g. kiwi_get_products. On Windows use
double backslashes in JSON paths. Full walkthrough in SETUP.md.
Environment variables
Var | Required | Notes |
| yes | Base URL only, no path. e.g. |
| yes | Kiwi login (email or username) |
| yes | Kiwi password |
| no | Set to |
Credentials sit in
~/.claude.jsonin plain text (same posture as most MCP client configs). Keep that file private and out of version control.
Related MCP server: testrail-mcp-server
Verify
1. Auth + connectivity smoke test (hits a real instance):
# macOS / Linux
KIWI_URL=https://kiwi.example.com KIWI_USERNAME=you KIWI_PASSWORD=secret npm run smoke# Windows PowerShell
$env:KIWI_URL="https://kiwi.example.com"; $env:KIWI_USERNAME="you"; $env:KIWI_PASSWORD="secret"; npm run smokeExpect Auth OK and a list of products. TLS error on an internal CA? Prefix
KIWI_INSECURE_TLS=1 (then add the same to your config env).
2. Offline checks (no network):
npm run list-tools # prints all 49 registered tools
npm test # lint/registration sanity (alias of list-tools)Remote / hosted (HTTP) — experimental
Status: built and smoke-tested, not battle-tested in production. Only host this if you understand the exposure: it puts an authenticated path to your Kiwi instance on whatever network the host is reachable from, protected by a URL/bearer token. Put it behind a real host with a dedicated Kiwi service account, not a personal tunnel with your own login.
The stdio server only works with a local Claude (CLI / desktop app). To use it from claude.ai in a browser, run the HTTP transport on a publicly reachable host and add it as a custom connector.
1. Generate an auth token (any client that knows it can call the server):
npm run gen-token2. Run the HTTP server:
$env:KIWI_URL="https://kiwi.example.com"
$env:KIWI_USERNAME="you@example.com"
$env:KIWI_PASSWORD="..."
$env:MCP_AUTH_TOKEN="<token from step 1>"
npm run httpListens on 127.0.0.1:8787 by default (MCP_HTTP_HOST / MCP_HTTP_PORT to change).
GET /health is open; the MCP endpoint is POST /<token>/mcp (token in the path, so no
custom headers are needed) or POST /mcp with an Authorization: Bearer <token> header.
3. Expose it with a tunnel from your PC:
cloudflared tunnel --url http://localhost:8787
# or: ngrok http 87874. Add the connector in claude.ai → Settings → Connectors → Add custom connector,
URL = https://<tunnel-host>/<token>/mcp.
Env vars specific to the HTTP server:
Var | Default | Notes |
| — | Required (min 32 chars). Callers pass it in the URL path or as a bearer token. |
|
| Set |
|
| |
|
| Per-IP request cap. |
| — |
|
A Dockerfile is included (node src/http.js, port 8787). npm run http-smoke starts
the server on a random port and runs initialize / tools/list / tools/call / bad-token
against live Kiwi.
Tool map
Grouped by area. Names and grouping mirror the @uarlouski/testrail-mcp-server MCP to
make a TestRail migration mostly mechanical.
Area | Tools |
Discovery |
|
Test cases |
|
Test plans |
|
Test runs |
|
Executions (results) |
|
Raw / generic |
|
Not ported (no Kiwi equivalent)
Shared steps — Kiwi has no shared-step concept.
Milestones — use product versions / builds instead.
Templates, configurations — Kiwi uses Environments instead; reach them via
kiwi_rpcif the Environments plugin is enabled.get_case_fields/resolve_case_field— Kiwi has no per-product custom-field schema RPC. Custom key/value data lives onTestCase.properties(kiwi_get_test_casewithinclude_properties: true).
Field-name gotchas (TestRail habits that will bite)
TestRail | Kiwi |
|
|
|
|
|
|
|
|
result | Kiwi status ids — call |
For the authoritative shape of any object, call kiwi_rpc with <Model>.filter and one
example id, or read the RPC docs.
Requirements
Node.js 18+ (uses global
fetch)A Kiwi TCMS account with API access on the instance you point at
Every tool runs with your account's Kiwi permissions. Kiwi enforces per-model
add/change/delete/view grants, so a login can easily be able to create a test case
but not edit or delete one. When a grant is missing Kiwi returns error -32098
("Authentication failed when calling <Method>") — that's a permissions problem, not a
bug. Common ones: auth.view_user for kiwi_get_users; testcases.change_testcase /
testcases.delete_testcase for kiwi_update_test_case / kiwi_delete_test_case;
likewise for testplans.*, testruns.*, testexecutions.*. Grant the matching
permission (Kiwi admin → user/group), or use an account that has it.
Verified against a live Kiwi 16.3 instance: all read tools, kiwi_create_test_case and
kiwi_add_test_case_comment work end-to-end; update/delete were correctly refused
on a create-only account with -32098.
Contributing
Issues and PRs welcome. Handy while developing:
npm run list-tools # every registered tool, offline
npm run smoke # live Auth.login + Product.filter (needs KIWI_* env)
npm run http-smoke # spins up the HTTP server and runs initialize/list/call/healthLicense
Available Tools
49 toolskiwi_add_case_to_planB
Link an existing test case to a test plan.
Inputs: case_id (required), plan_id (required).
kiwi_add_case_to_runA
Add a test case to a run. This creates the TestExecution rows for that case.
Inputs: run_id (required), case_id (required).
kiwi_add_execution_commentB
Add a comment to a test execution.
Inputs: comment (required), execution_id (required).
kiwi_add_execution_linkB
Attach an external URL (bug link, evidence) to a test execution.
Inputs: url (required), execution_id (required), name, is_defect.
kiwi_add_plan_tagB
Attach a tag (by name) to a test plan.
Inputs: tag (required), plan_id (required).
kiwi_add_run_attachmentA
Attach a file to a test run. Provide base64-encoded content.
Inputs: run_id (required), filename (required), content_base64 (required).
kiwi_add_run_tagB
Attach a tag (by name) to a test run.
Inputs: tag (required), run_id (required).
kiwi_add_test_case_attachmentB
Attach a file to a test case. Provide base64-encoded content.
Inputs: case_id (required), filename (required), content_base64 (required).
kiwi_add_test_case_commentC
Add a comment to a test case.
Inputs: case_id (required), comment (required).
kiwi_add_test_case_componentB
Attach a component (by name) to a test case.
Inputs: case_id (required), component (required).
kiwi_add_test_case_tagA
Attach a tag (by name) to a test case. The tag is created if it does not exist.
Inputs: tag (required), case_id (required).
kiwi_create_test_caseA
Create a test case. values must include at least: summary, category_id (or category), priority_id (or priority), case_status_id (or case_status). Optional: text, notes, is_automated, script, extra_link, requirement, default_tester_id. Returns the created case.
Inputs: values (required).
kiwi_create_test_planA
Create a test plan. values needs: name, text, product_id (or product), product_version_id (or product_version), type_id (or type). Optional: parent_id, is_active, extra_link.
Inputs: values (required).
kiwi_create_test_runA
Create a test run. values needs: summary, plan_id (or plan), build_id (or build), manager_id (or manager). Optional: notes, default_tester_id, planned_start, planned_stop.
Inputs: values (required).
kiwi_delete_entityA
Generic delete: calls .remove with the given ORM filter dict. DESTRUCTIVE. model e.g. "TestCase", "TestRun", "TestExecution", "Tag". query e.g. {"id": 5} or {"id__in": [1,2,3]}.
Inputs: model (required), query (required).
kiwi_delete_test_caseA
Permanently delete test cases matching an ORM filter dict. DESTRUCTIVE. Pass e.g. {"id": 123} or {"id__in": [1,2,3]}.
Inputs: query (required).
kiwi_delete_test_runA
Permanently delete test runs matching an ORM filter dict. DESTRUCTIVE. Pass e.g. {"id": 42}.
Inputs: query (required).
kiwi_export_test_cases_for_ragA
Bulk-export full text of test cases matching query, flattened for RAG / review (id, summary, category, priority, status, text, notes). Mirrors TestRail export_cases_for_rag.
Inputs: query (required), limit.
kiwi_get_buildsA
List builds. Typical filter: {"version__product": <product_id>} or {"version": <version_id>}.
Inputs: query.
kiwi_get_case_statusesA
List TestCase statuses (CONFIRMED / PROPOSED / ...) with their ids.
Inputs: query.
kiwi_get_categoriesA
List test-case categories for a product (closest thing to TestRail sections). Typical filter: {"product": <product_id>}.
Inputs: query.
kiwi_get_classificationsA
List product classifications with their ids.
Inputs: query.
kiwi_get_componentsA
List components. Typical filter: {"product": <product_id>}.
Inputs: query.
kiwi_get_execution_commentsB
Get the comments on a test execution.
Inputs: execution_id (required).
kiwi_get_execution_historyA
Return the change history for a test execution.
Inputs: execution_id (required).
kiwi_get_execution_linksA
List external links attached to a test execution.
Inputs: execution_id (required).
kiwi_get_execution_statusesA
List TestExecution statuses (PASSED / FAILED / BLOCKED / ...) with their ids. Needed before updating an execution result.
Inputs: query.
kiwi_get_plan_typesA
List test-plan types (Unit / Integration / Function / ...) with their ids.
Inputs: query.
kiwi_get_prioritiesB
List test-case priorities and their ids.
Inputs: query.
kiwi_get_productsB
List Kiwi products (the TestRail 'project' equivalent). Filter dict optional.
Inputs: query.
kiwi_get_run_casesA
List the test cases currently in a run.
Inputs: run_id (required).
kiwi_get_tagsA
List tags (the TestRail 'labels' equivalent). Filter e.g. {"name__startswith": "reg"}.
Inputs: query.
kiwi_get_test_caseA
Fetch one test case by id, optionally with its comments, custom properties and attachment list.
Inputs: case_id (required), include_comments, include_properties, include_attachments.
kiwi_get_test_case_historyC
Return the change history for a test case.
Inputs: case_id (required).
kiwi_get_test_casesA
Search test cases. query is a Kiwi ORM filter dict. Common keys: {"plan": <plan_id>}, {"category__product": <product_id>}, {"summary__icontains": "data usage"}, {"case_status__name": "CONFIRMED"}.
Inputs: query.
kiwi_get_test_executionsA
Search test executions (results). query common keys: {"run": <run_id>}, {"run": <run_id>, "case": <case_id>}, {"status__name": "FAILED"}, {"tested_by__username": "sqa1"}.
Inputs: query.
kiwi_get_test_plansA
Search test plans. query common keys: {"product": <product_id>}, {"name__icontains": "regression"}, {"is_active": true}.
Inputs: query.
kiwi_get_test_runsA
Search test runs. query common keys: {"plan": <plan_id>}, {"build__version__product": <product_id>}, {"summary__icontains": "trip"}, {"stop_date__isnull": true} (still open).
Inputs: query.
kiwi_get_usersA
List Kiwi users. Filter e.g. {"username": "sqa1"} or {"email__icontains": "acme.com"}. Requires the 'auth.view_user' permission on your Kiwi account; without it Kiwi returns error -32098 ("Authentication failed").
Inputs: query.
kiwi_get_versionsA
List product versions. Typical filter: {"product": <product_id>}.
Inputs: query.
kiwi_remove_case_from_planB
Unlink a test case from a test plan.
Inputs: case_id (required), plan_id (required).
kiwi_remove_case_from_runB
Remove a test case (and its executions) from a run.
Inputs: run_id (required), case_id (required).
kiwi_rpcA
Call ANY Kiwi JSON-RPC method directly. method e.g. "TestCase.filter", "TestPlan.tree", "Bug.report". params is the POSITIONAL argument array Kiwi expects (usually a single dict for *.filter, or [id, {patch}] for *.update). Unguarded — you are responsible for correct method + params. Full method list: https://kiwitcms.readthedocs.io/en/latest/modules/tcms.rpc.api.html
Inputs: method (required), params.
kiwi_update_executions_bulkA
Record results for many cases in one run (mirrors TestRail add_results_for_cases). For each item, finds the execution for {run_id, case_id}, sets its status, and optionally adds a comment. status may be a status id (number) or name (string).
Inputs: run_id (required), results (required).
kiwi_update_test_caseA
Update one test case. values is a partial field dict (e.g. {"summary": "...", "text": "...", "case_status_id": 2}).
Inputs: values (required), case_id (required).
kiwi_update_test_casesA
Apply the same values patch to many cases (mirrors TestRail update_cases). Runs one TestCase.update per id and reports per-id success/failure.
Inputs: values (required), case_ids (required).
kiwi_update_test_executionA
Update one execution. values e.g. {"status_id": 2} (see kiwi_get_execution_statuses), or {"tested_by_id": 5, "stop_date": "2026-09-08 16:30:00"}.
Inputs: values (required), execution_id (required).
kiwi_update_test_planB
Update a test plan with a partial field dict.
Inputs: values (required), plan_id (required).
kiwi_update_test_runA
Update a test run with a partial field dict (e.g. {"stop_date": "2026-09-08 17:00:00"}).
Inputs: run_id (required), values (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 49 tools
Most tools map to a distinct resource and action, and the descriptions make the case/plan/run/execution domains fairly clear. The main ambiguities are kiwi_delete_entity and kiwi_rpc, which intentionally overlap with specific tools, plus kiwi_get_run_cases vs kiwi_get_test_executions for retrieving run-level case data.
The vast majority follow a consistent kiwi_ + verb_noun pattern: get_, create_, update_, delete_, add_, remove_. Minor deviations include the generic kiwi_delete_entity, the raw kiwi_rpc, and the slightly inconsistent kiwi_update_executions_bulk versus kiwi_update_test_execution.
49 tools is well into the over-scoped range and creates a heavy tool-selection burden for agents. Even though Kiwi TCMS is a broad test-management domain, the count is inflated by many reference-list tools and singular/bulk/comment/link variants that could be consolidated.
Core workflows are well covered: test cases, plans, runs, executions, comments, attachments, links, history, and bulk updates. Gaps exist around removing comments/tags/links and creating reference entities like builds, versions, or products through dedicated wrappers, but kiwi_rpc and kiwi_delete_entity provide fallbacks for those edge cases.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Find, vet, and run MCP tools through a secure audited gateway with prompt-injection risk scoring
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that exposes the QMetry Test Management for Jira Cloud REST API as tools for MCP-compatible clients. It enables users to manage test cases, test cycles, test executions, test plans, folders, and automation rules through natural language interactions.3057 npmMIT
- AlicenseBqualityDmaintenanceEnables TestRail test management through MCP tools, allowing users to manage projects, test cases, runs, and results via natural language.2531 npmMIT
- 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-
- AlicenseBqualityCmaintenanceMCP server providing full access to Kiwi TCMS via JSON-RPC, with 68 tools for test plans, cases, runs, executions, and reference data. It supports named arguments, default project, and easy integration with MCP clients.6810 npmMIT