qTest On-Premise MCP Server
Provides tools for interacting with qTest Manager (Tricentis), enabling AI agents to manage projects, modules, test cases, steps, requirements, traceability links, test cycles, suites, runs, and execution results via the qTest REST API.
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., "@qTest On-Premise MCP Server Find test cases linked to requirement REQ-100"
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.
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 buildThis 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/LinuxCopy-Item .env.example .env # Windows PowerShellVariable | Required | Default | Description |
| Yes | – | Base URL of your on-prem qTest, e.g. |
| One of token or user/pass | – | Static bearer/API token. Generate in qTest under Profile → API & SDK. |
| – | – | Username for password-grant login (used only when |
| – | – | Password for password-grant login. |
| No |
| Basic-auth seed used on the |
| No |
| When |
| No |
| When |
| No |
| Per-request timeout in milliseconds. |
| No |
| When |
| No |
|
|
Auth precedence: if
QTEST_TOKENis set it is always used. Otherwise the server logs in withQTEST_USERNAME/QTEST_PASSWORD, caches the token, refreshes it ~60s before expiry, and retries once on a401.
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 |
| List accessible projects (optionally only those assigned to you). |
| Get a single project by ID. |
Test Design — Modules
Tool | Description |
| List root / child modules, or filter by name. |
| Create a module or sub-module. |
| Rename/update a module or its custom fields. |
| Delete a module (cascades). |
Test Design — Test Cases & Steps
Tool | Description |
| List test cases (optionally scoped to a module, name-filtered). |
| Get one test case with its steps. |
| Create a test case, optionally with ordered steps and custom fields. |
| Update name/description/precondition/fields (new version). |
| Append a step to a test case. |
| Delete a test case. |
Requirements
Tool | Description |
| List requirements (optionally scoped to a module). |
| Get one requirement. |
| Create a requirement under a module. |
| Update or move a requirement. |
| Delete a requirement. |
Traceability & Linking
Tool | Description |
| Link one or more test cases as coverage of a requirement. |
| Remove those coverage links. |
| List the test cases covering a requirement. |
| Generic link/unlink between any two artifact types (test-cases, requirements, defects, test-runs). |
| Requirement traceability matrix report. |
Test Execution
Tool | Description |
| List root/child test cycles. |
| Create a cycle (root or nested). |
| Delete a cycle (cascades). |
| List suites under a cycle/release. |
| Create a suite. |
| Create runs in a suite from test case IDs. |
| List runs under a parent. |
| Get a run with its latest status. |
| Record an execution result (Passed/Failed/…). |
Cross-cutting
Tool | Description |
| Search artifacts with qTest Query Language (QQL). |
| Discover field IDs/allowed values for an artifact type. |
| Verify auth / identity. |
| Attach a base64 file to an artifact. |
| 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 dashboardRequirements & 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=debugonly 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 serverSmoke 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 testis not defined). Verification is manual: build, connect an MCP client (or the MCP Inspector), and exercisetools/list/tools/callagainst a real or sandboxed qTest instance.
Troubleshooting
Symptom | Likely cause / fix |
| Set the base URL env var. |
| Provide |
| Token expired/invalid, or wrong |
| Self-signed cert — set |
| Verify the |
A | Enable it via the corresponding env flag. |
See ARCHITECTURE.md for the internal design.
License
MIT — see LICENSE. "# soco-qtest-mcp"
Available Tools
31 toolsqtest_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 userARead-only
Return the profile of the authenticated qTest user. Useful for verifying connectivity and permissions.
Inputs: no named parameters.
qtest_get_projectGet a qTest projectARead-only
Fetch a single qTest project by its numeric ID.
Inputs: projectId (required).
qtest_get_requirementGet a requirementARead-only
Fetch a single requirement by ID.
Inputs: projectId (required), requirementId (required).
qtest_get_requirement_coverageGet requirement coverageARead-only
List the test cases currently linked to (covering) a requirement.
Inputs: projectId (required), requirementId (required).
qtest_get_test_caseGet a test caseARead-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 runARead-only
Fetch a single test run by ID, including its latest status.
Inputs: projectId (required), testRunId (required).
qtest_get_traceability_matrixGet traceability matrixARead-only
Retrieve the requirement traceability matrix report: requirements with their covering test cases. Useful for coverage audits.
Inputs: projectId (required), page, size, fieldIds.
qtest_link_artifactsLink artifacts (generic)A
Generic object-linking between any two qTest artifact types. Link the source object (objectType/objectId) to the given target IDs of linkType. Example: link a 'test-cases' object to 'defects'. Supported types: test-cases, requirements, defects, test-runs.
Inputs: linkType (required), objectId (required), projectId (required), targetIds (required), +2 more.
qtest_link_test_cases_to_requirementLink test cases to a requirementA
Create coverage links between a requirement and one or more test cases. This is the primary traceability action: it marks the listed test cases as covering the requirement. IDs are numeric test case IDs (use qtest_list_test_cases to find them).
Inputs: projectId (required), testCaseIds (required), requirementId (required).
qtest_list_fieldsList fields for an artifact typeARead-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 modulesARead-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 projectsARead-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 requirementsARead-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 casesARead-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 cyclesARead-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 runsARead-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 suitesARead-only
List test suites under a test cycle (or release). Provide parentId and parentType.
Inputs: parentId (required), projectId (required), parentType.
qtest_searchSearch artifacts (qTest Query Language)ARead-only
Search a project's artifacts using qTest Query Language (QQL). Example queries: "Name ~ 'login'", "Status = 'Approved'", "'Automation' = 'Yes' and Priority = 'High'". Specify the artifact type to search.
Inputs: query (required), projectId (required), objectType (required), fields, +1 more.
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_unlink_test_cases_from_requirementUnlink test cases from a requirementB
Remove coverage links between a requirement and one or more test cases.
Inputs: projectId (required), testCaseIds (required), requirementId (required).
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
Scored across 31 tools
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.
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.
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.
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
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Free test management over MCP: projects, test cases, plans, runs, environments and tasks.
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityFmaintenanceQA 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.1551 npm23MIT
- 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.3064 npmMIT
- AlicenseAqualityDmaintenanceThis 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 suites947 npm1MIT
- AlicenseCqualityCmaintenanceProduction-ready MCP server for Allure TestOps, enabling test case, launch, test result, and test plan management via natural language.100730 npm2MIT