Skip to main content
Glama

kiwi-tcms-mcp

license: MIT node: >=18 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_rpc escape 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 TCMS

Coming 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 install

Wire 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.json on Windows), or run claude mcp add.

  • Claude Desktop — mcpServers in claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS); use an absolute path to node.

  • Cursor / Cline / Continue / Zed — their MCP settings use the same command / args / env shape.

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

KIWI_URL

yes

Base URL only, no path. e.g. https://kiwi.example.com

KIWI_USERNAME

yes

Kiwi login (email or username)

KIWI_PASSWORD

yes

Kiwi password

KIWI_INSECURE_TLS

no

Set to 1 only if the host's TLS cert is not trusted by Node (self-signed / internal CA). Disables cert verification for the whole process — prefer trusting the CA instead.

Credentials sit in ~/.claude.json in 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 smoke

Expect 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-token

2. 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 http

Listens 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 8787

4. 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

MCP_AUTH_TOKEN

—

Required (min 32 chars). Callers pass it in the URL path or as a bearer token.

MCP_HTTP_HOST

127.0.0.1

Set 0.0.0.0 in a container.

MCP_HTTP_PORT

8787

MCP_RATE_PER_MIN

120

Per-IP request cap.

MCP_ALLOW_NO_AUTH

—

1 disables the token check entirely. Don't.

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

kiwi_get_products, kiwi_get_versions, kiwi_get_builds, kiwi_get_categories, kiwi_get_components, kiwi_get_tags, kiwi_get_priorities, kiwi_get_users, kiwi_get_execution_statuses, kiwi_get_case_statuses, kiwi_get_plan_types, kiwi_get_classifications

Test cases

kiwi_get_test_cases, kiwi_get_test_case, kiwi_create_test_case, kiwi_update_test_case, kiwi_update_test_cases, kiwi_delete_test_case, kiwi_get_test_case_history, kiwi_add_test_case_comment, kiwi_add_test_case_tag, kiwi_add_test_case_component, kiwi_add_test_case_attachment, kiwi_export_test_cases_for_rag

Test plans

kiwi_get_test_plans, kiwi_create_test_plan, kiwi_update_test_plan, kiwi_add_case_to_plan, kiwi_remove_case_from_plan, kiwi_add_plan_tag

Test runs

kiwi_get_test_runs, kiwi_create_test_run, kiwi_update_test_run, kiwi_delete_test_run, kiwi_add_case_to_run, kiwi_remove_case_from_run, kiwi_get_run_cases, kiwi_add_run_tag, kiwi_add_run_attachment

Executions (results)

kiwi_get_test_executions, kiwi_update_test_execution, kiwi_update_executions_bulk, kiwi_add_execution_comment, kiwi_get_execution_comments, kiwi_add_execution_link, kiwi_get_execution_links, kiwi_get_execution_history

Raw / generic

kiwi_rpc, kiwi_delete_entity

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_rpc if 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 on TestCase.properties (kiwi_get_test_case with include_properties: true).

Field-name gotchas (TestRail habits that will bite)

TestRail

Kiwi

title

summary

custom_steps / custom_expected

text (single rich field)

suite_id + section_id

category_id (+ link to a plan)

type_id

is_automated (bool) + category

result status_id 1..5 (TestRail scale)

Kiwi status ids — call kiwi_get_execution_statuses first

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/health

License

MIT

Available Tools

49 tools
kiwi_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_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_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

    B3.4/5.0

    Scored across 49 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      30
      57 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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
      -
    • A
      license
      B
      quality
      C
      maintenance
      MCP 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.
      68
      10 npm
      MIT