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.

Related MCP server: QTM4J MCP Server

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

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

Test Design — Modules

Test Design — Test Cases & Steps

Requirements

Traceability & Linking

Test Execution

Cross-cutting

† 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

See ARCHITECTURE.md for the internal design.

License

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