Skip to main content
Glama
qTest On-Premise MCP Server

qTest On-Premise MCP Server

by VaniTTC

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

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"

Available Tools

31 tools
qtest_add_attachmentAdd an attachmentA

Attach a file (provided as base64 content) to a qTest artifact such as a test case, requirement, defect, or test log.

Inputs: fileName (required), objectId (required), projectId (required), objectType (required), +2 more.

qtest_add_test_runsAdd test runs to a suiteA

Create test runs inside a test suite from a list of test case IDs. Each run represents one executable instance of a test case. Use qtest_list_test_cases to find test case IDs.

Inputs: projectId (required), testCaseIds (required), testSuiteId (required).

qtest_add_test_stepAdd a test stepA

Append a single test step (action + expected result) to an existing test case.

Inputs: projectId (required), testCaseId (required), description (required), expected.

qtest_create_moduleCreate a moduleA

Create a Test Design module (folder). Omit parentId to create at the root, or supply parentId to nest it under an existing module.

Inputs: name (required), projectId (required), parentId, description.

qtest_create_requirementCreate a requirementA

Create a requirement under a module. Supply parentId for the containing module and optional custom fields (fieldId -> value).

Inputs: name (required), parentId (required), projectId (required), fields, +1 more.

qtest_create_test_caseCreate a test caseA

Create a test case inside a module. You can include ordered test steps and custom field values (fieldId -> value map).

Inputs: name (required), parentId (required), projectId (required), steps, +3 more.

qtest_create_test_cycleCreate a test cycleA

Create a test cycle. Omit parentId for a root cycle, or nest under a release or another cycle by supplying parentId and parentType.

Inputs: name (required), projectId (required), parentId, parentType, +1 more.

qtest_create_test_suiteCreate a test suiteA

Create a test suite under a test cycle (or release). Test runs are added to suites.

Inputs: name (required), parentId (required), projectId (required), parentType.

qtest_get_current_userGet current userA
Read-only

Return the profile of the authenticated qTest user. Useful for verifying connectivity and permissions.

Inputs: no named parameters.

qtest_get_projectGet a qTest projectA
Read-only

Fetch a single qTest project by its numeric ID.

Inputs: projectId (required).

qtest_get_requirementGet a requirementA
Read-only

Fetch a single requirement by ID.

Inputs: projectId (required), requirementId (required).

qtest_get_requirement_coverageGet requirement coverageA
Read-only

List the test cases currently linked to (covering) a requirement.

Inputs: projectId (required), requirementId (required).

qtest_get_test_caseGet a test caseA
Read-only

Fetch a single test case by ID, including its test steps and properties.

Inputs: projectId (required), testCaseId (required).

qtest_get_test_runGet a test runA
Read-only

Fetch a single test run by ID, including its latest status.

Inputs: projectId (required), testRunId (required).

qtest_get_traceability_matrixGet traceability matrixA
Read-only

Retrieve the requirement traceability matrix report: requirements with their covering test cases. Useful for coverage audits.

Inputs: projectId (required), page, size, fieldIds.

qtest_list_fieldsList fields for an artifact typeA
Read-only

List the system and custom fields (with their numeric IDs and allowed values) for an artifact type in a project. Use this to discover field IDs needed by the 'fields' parameter on create/update tools.

Inputs: projectId (required), objectType (required).

qtest_list_modulesList modulesA
Read-only

List Test Design modules (folders). With no parentId, returns root modules. Provide parentId to list child modules. Provide search to filter by name (case-insensitive substring).

Inputs: projectId (required), search, parentId.

qtest_list_projectsList qTest projectsA
Read-only

List all qTest projects the authenticated user can access. Returns id, name and status for each. Use this first to discover the projectId required by most other tools.

Inputs: assignedOnly.

qtest_list_requirementsList requirementsA
Read-only

List requirements in a project, optionally scoped to a parent module. Supports client-side filtering by name substring.

Inputs: projectId (required), search, maxItems, parentId.

qtest_list_test_casesList test casesA
Read-only

List test cases in a project, optionally scoped to a module via parentId. Supports client-side filtering by name substring.

Inputs: projectId (required), search, maxItems, parentId.

qtest_list_test_cyclesList test cyclesA
Read-only

List test cycles. With no parentId, returns root-level cycles. Provide parentId (and the matching parentType) to list children. Supports name filtering.

Inputs: projectId (required), search, parentId, parentType.

qtest_list_test_runsList test runsA
Read-only

List test runs under a parent (test suite or test cycle). Provide parentId and parentType.

Inputs: parentId (required), projectId (required), parentType.

qtest_list_test_suitesList test suitesA
Read-only

List test suites under a test cycle (or release). Provide parentId and parentType.

Inputs: parentId (required), projectId (required), parentType.

qtest_submit_test_logLog a test resultA

Record an execution result (test log) against a test run. Provide a status such as 'Passed', 'Failed', 'Blocked', or 'Incomplete'. Optionally include a note and execution start/end timestamps (ISO 8601).

Inputs: status (required), projectId (required), testRunId (required), note, +2 more.

qtest_update_moduleUpdate a moduleA

Update a module's name, description, or custom fields. Provide fields as a map of fieldId -> value.

Inputs: moduleId (required), projectId (required), name, fields, +1 more.

qtest_update_requirementUpdate a requirementA

Update a requirement's name, description, or custom fields. Optionally move it to a different parent module.

Inputs: projectId (required), requirementId (required), name, fields, +2 more.

qtest_update_test_caseUpdate a test caseA

Update a test case's name, description, precondition, or custom fields. Creates a new version in qTest.

Inputs: projectId (required), testCaseId (required), name, fields, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 31 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (e.g., get vs list vs create vs update). The two coverage-related tools are clearly differentiated: one for a single requirement, the other for a full traceability matrix. No two tools appear to do the same thing.

    Naming Consistency5/5

    All tool names follow the qtest_<verb>_<noun> pattern. Verbs are consistent (get/list/create/update/add/submit/link/unlink/search), and plural forms are used for list operations while singular is used for single-item fetches. No mixed conventions or style inconsistencies exist.

    Tool Count3/5

    The server exposes 31 tools, which is heavier than the typical sweet spot. While the breadth of qTest's test management API justifies many of them, there is some conceptual overlap (e.g., qtest_get_requirement_coverage vs qtest_get_traceability_matrix) that could be consolidated. The count is borderline but not chaotic.

    Completeness2/5

    The tool set covers create, read, and update for many artifact types, but lacks delete operations entirely (no delete for modules, test cases, requirements, cycles, suites, or runs). Update is also missing for cycles and suites. This creates lifecycle dead ends and limits cleanup ability, a significant gap in a comprehensive test management tool.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      QA Sphere MCP server that enables Large Language Models to interact directly with test management system test cases, supporting AI-powered development workflows and test case discovery.
      15
      51 npm
      23
      MIT
    • 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
      64 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      This is an unofficial, community-built MCP server for qTest Manager. Not affiliated with or endorsed by Tricentis. Browse projects, modules, and test cases Create/delete test design modules Create and manage test execution cycles Add test cases into execution suites
      9
      47 npm
      1
      MIT