qTest On-Premise MCP Server

Disclaimer: This is an unofficial, community-built MCP (Model Context Protocol) server for qTest Manager (On-Premise). It is not affiliated with or endorsed by Tricentis. Inspired by, and a substantial enhancement of, Usman-Ghani123/qtest-mcp-server.

An MCP server that lets AI assistants (Claude Desktop, Claude Code, and any MCP-compatible client) drive a self-hosted qTest Manager instance through natural language — manage projects, modules, test cases, test steps, requirements, requirement↔test-case traceability links, test cycles, suites, runs, and execution results.

It is written in TypeScript, talks to qTest over the standard /api/v3 REST API, and communicates with clients over stdio.

---

What's new vs. the reference server

The reference project covered projects, modules, test cases, and execution scaffolding. This server keeps that surface and adds:

• On-prem first: configurable base URL, optional self-signed TLS tolerance, and tolerant base-URL parsing.
• Dual authentication: a static bearer/API token or username/password login that fetches and auto-refreshes a token (with 401 retry).
• Requirements management: full CRUD for requirements.
• Traceability: link / unlink test cases to requirements, read requirement coverage, a generic artifact-linking tool, and the requirement traceability matrix report.
• Richer test design: create test cases with ordered steps, add steps, update test cases, list/discover fields (so the model can populate custom fields by ID).
• Execution & results: cycles, suites, add runs from test cases, list/get runs, and submit test logs (pass/fail results).
• QQL search across artifact types, attachments, and an optional raw request escape hatch.
• Production hardening: timeouts, retry with backoff on 429/5xx, structured stderr logging, destructive-action gating, and friendly, LLM-readable error messages.

---

Prerequisites

• Node.js 18+ (developed and tested on Node 22).
• A qTest Manager On-Premise instance reachable from where the server runs.
• Either a qTest API token, or a username/password with API access.

---

Installation

git clone <your-fork-url> qtest-onprem-mcp
cd qtest-onprem-mcp
npm install
npm run build

# Windows PowerShell equivalent
git clone <your-fork-url> qtest-onprem-mcp
cd qtest-onprem-mcp
npm install
npm run build

This produces dist/index.js, the compiled entry point your MCP client will launch (dist/ is not committed — you must build it locally, or run npm run dev below).

For local development without building, use npm run dev (watch mode via tsx).

---

Configuration

All configuration is via environment variables. Copy .env.example to .env for local runs, or set them in your MCP client config (recommended).

cp .env.example .env        # macOS/Linux

Copy-Item .env.example .env # Windows PowerShell

Variable	Required	Default	Description
QTEST_BASE_URL	Yes	–	Base URL of your on-prem qTest, e.g. https://qtest.mycompany.internal. A trailing /api/v3 is tolerated and stripped.
QTEST_TOKEN	One of token or user/pass	–	Static bearer/API token. Generate in qTest under Profile → API & SDK.
QTEST_USERNAME	–	–	Username for password-grant login (used only when QTEST_TOKEN is empty).
QTEST_PASSWORD	–	–	Password for password-grant login.
QTEST_LOGIN_CLIENT	No	qtest	Basic-auth seed used on the /oauth/token request. Override if your admin configured a specific client id.
QTEST_ENABLE_DESTRUCTIVE	No	false	When true, registers the delete-* tools.
QTEST_ENABLE_RAW_REQUEST	No	false	When true, registers the generic qtest_request tool.
QTEST_TIMEOUT_MS	No	30000	Per-request timeout in milliseconds.
QTEST_INSECURE_TLS	No	false	When true, disables TLS certificate verification (for internal self-signed certs only).
QTEST_LOG_LEVEL	No	info	error | warn | info | debug. All logs go to stderr.

Auth precedence: if QTEST_TOKEN is set it is always used. Otherwise the server logs in with QTEST_USERNAME/QTEST_PASSWORD, caches the token, refreshes it ~60s before expiry, and retries once on a 401.

Connect your MCP client

A ready-to-edit example lives in .mcp.example.json. Minimal Claude Desktop / Claude Code entry:

{
  "mcpServers": {
    "qtest-onprem": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "QTEST_BASE_URL": "https://qtest.mycompany.internal",
        "QTEST_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Use an absolute path to dist/index.js if your client does not run from the project root.

---

Available tools

Most tools require a numeric projectId — call qtest_list_projects first to discover it.

Projects

Tool	Description
qtest_list_projects	List accessible projects (optionally only those assigned to you).
qtest_get_project	Get a single project by ID.

Test Design — Modules

Tool	Description
qtest_list_modules	List root / child modules, or filter by name.
qtest_create_module	Create a module or sub-module.
qtest_update_module	Rename/update a module or its custom fields.
qtest_delete_module †	Delete a module (cascades).

Test Design — Test Cases & Steps

Tool	Description
qtest_list_test_cases	List test cases (optionally scoped to a module, name-filtered).
qtest_get_test_case	Get one test case with its steps.
qtest_create_test_case	Create a test case, optionally with ordered steps and custom fields.
qtest_update_test_case	Update name/description/precondition/fields (new version).
qtest_add_test_step	Append a step to a test case.
qtest_delete_test_case †	Delete a test case.

Requirements

Tool	Description
qtest_list_requirements	List requirements (optionally scoped to a module).
qtest_get_requirement	Get one requirement.
qtest_create_requirement	Create a requirement under a module.
qtest_update_requirement	Update or move a requirement.
qtest_delete_requirement †	Delete a requirement.

Traceability & Linking

Tool	Description
qtest_link_test_cases_to_requirement	Link one or more test cases as coverage of a requirement.
qtest_unlink_test_cases_from_requirement	Remove those coverage links.
qtest_get_requirement_coverage	List the test cases covering a requirement.
qtest_link_artifacts	Generic link/unlink between any two artifact types (test-cases, requirements, defects, test-runs).
qtest_get_traceability_matrix	Requirement traceability matrix report.

Test Execution

Tool	Description
qtest_list_test_cycles	List root/child test cycles.
qtest_create_test_cycle	Create a cycle (root or nested).
qtest_delete_test_cycle †	Delete a cycle (cascades).
qtest_list_test_suites	List suites under a cycle/release.
qtest_create_test_suite	Create a suite.
qtest_add_test_runs	Create runs in a suite from test case IDs.
qtest_list_test_runs	List runs under a parent.
qtest_get_test_run	Get a run with its latest status.
qtest_submit_test_log	Record an execution result (Passed/Failed/…).

Cross-cutting

Tool	Description
qtest_search	Search artifacts with qTest Query Language (QQL).
qtest_list_fields	Discover field IDs/allowed values for an artifact type.
qtest_get_current_user	Verify auth / identity.
qtest_add_attachment	Attach a base64 file to an artifact.
qtest_request ‡	Raw authenticated API call (advanced).

† Registered only when QTEST_ENABLE_DESTRUCTIVE=true. ‡ Registered only when QTEST_ENABLE_RAW_REQUEST=true.

---

Usage examples (natural language)

Once connected, you can prompt your assistant like this:

Discover and browse

List all my qTest projects.
List the modules in project 100001.
Show test cases in module 60000001 of project 100001.

Author test design

In project 100001, create a test case named "Login with valid credentials"
under module 60000001 with steps:
  1. Open the login page — login page is shown
  2. Enter valid username and password — fields accept input
  3. Click Sign In — user lands on the dashboard

Requirements & traceability (the headline workflow)

Create a requirement "User can reset password" under module 70000002 in project 100001.
List test cases in module 60000001 whose name contains "password".
Link test cases 130000045 and 130000046 to requirement 88000123 in project 100001.
Show me the coverage for requirement 88000123.
Give me the traceability matrix for project 100001.

Execution & results

Create a test cycle "Release 3.0" in project 100001.
Add a suite "Smoke" under that cycle, then add test runs for test cases 130000045 and 130000046.
Mark test run 220000099 as Passed with the note "verified on build 3.0.12".

Search

Search project 100001 for test cases where Status = 'Approved' and Priority = 'High'.

---

Safety model

• Destructive tools are off by default. Deleting modules, test cases, requirements, and cycles cascades in qTest, so those tools only appear when you explicitly set QTEST_ENABLE_DESTRUCTIVE=true.
• The raw request tool is off by default. Enable it only if you need endpoints not yet wrapped by a dedicated tool.
• Secrets stay in env vars and are never logged. Set QTEST_LOG_LEVEL=debug only for troubleshooting.

---

Development

npm run dev        # watch mode (tsx), no build needed
npm run build      # compile TypeScript to dist/
npm run typecheck  # type-only check
npm start          # run the compiled server

Smoke test

With the server built, any MCP client can connect and call tools/list. The tools/list response should report 31 tools by default, or 36 when both QTEST_ENABLE_DESTRUCTIVE and QTEST_ENABLE_RAW_REQUEST are true (adds 4 delete tools + the raw request tool).

No automated test suite yet. This project currently has no unit/integration tests (npm test is not defined). Verification is manual: build, connect an MCP client (or the MCP Inspector), and exercise tools/list / tools/call against a real or sandboxed qTest instance.

---

Troubleshooting

Symptom	Likely cause / fix
FATAL: QTEST_BASE_URL is required	Set the base URL env var.
Authentication not configured	Provide QTEST_TOKEN, or both QTEST_USERNAME and QTEST_PASSWORD.
401 errors	Token expired/invalid, or wrong QTEST_LOGIN_CLIENT for password grant.
fetch failed / TLS errors on-prem	Self-signed cert — set QTEST_INSECURE_TLS=true on a trusted network.
404 on a known ID	Verify the projectId and artifact IDs; IDs are project-scoped.
A delete-* or qtest_request tool is missing	Enable it via the corresponding env flag.

See ARCHITECTURE.md for the internal design.

---

License

MIT — see LICENSE. "# soco-qtest-mcp"