io.github.salehrifai42/qtm4j-mcp-server
MCP server for QMetry Test Management for Jira (QTM4J): test cases, cycles, executions, plans.
Ask AI about io.github.salehrifai42/qtm4j-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about io.github.salehrifai42/qtm4j-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
QTM4J MCP Server
An MCP server with 42 tools for QMetry Test Management for Jira (QTM4J). Search and manage test cases, cycles, executions, plans, folders, automation rules, and project metadata from Claude Desktop, Claude Code, VS Code Copilot, Cursor, or any MCP-compatible client.
Distribution:
- npm:
qtm4j-mcp-server - MCP Registry:
io.github.salehrifai42/qtm4j-mcp-server - GitHub:
salehrifai42/qmetrymcp
Quick start (no clone required)
You need a QMetry API key (QMetry β API Keys) and Node.js 18+.
Claude Desktop
Edit your config file and restart Claude:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"qtm4j": {
"command": "npx",
"args": ["-y", "qtm4j-mcp-server@^0.1"],
"env": {
"QTM4J_API_KEY": "your-api-key-here",
"QTM4J_REGION": "US"
}
}
}
}
Claude Code (CLI)
claude mcp add qtm4j -e QTM4J_API_KEY=your-api-key-here -e QTM4J_REGION=US -- npx -y qtm4j-mcp-server@^0.1
VS Code (GitHub Copilot Agent mode)
Create .vscode/mcp.json in your workspace:
{
"servers": {
"qtm4j": {
"type": "stdio",
"command": "npx",
"args": ["-y", "qtm4j-mcp-server@^0.1"],
"env": {
"QTM4J_API_KEY": "${env:QTM4J_API_KEY}",
"QTM4J_REGION": "US"
}
}
}
}
Switch Copilot Chat to Agent mode and the qtm4j_* tools appear automatically.
Cursor
Add to ~/.cursor/mcp.json (or <project>/.cursor/mcp.json for project-level):
{
"mcpServers": {
"qtm4j": {
"command": "npx",
"args": ["-y", "qtm4j-mcp-server@^0.1"],
"env": { "QTM4J_API_KEY": "your-api-key-here" }
}
}
}
The example configs above pin the package to
^0.1so a future breaking release won't auto-upgrade you. Drop the@^0.1suffix if you'd rather always run the latest.
Global install (faster startup)
npx re-resolves the package on every launch, which adds a few seconds of startup latency. If you use the server frequently, install it globally and point your client at the binary directly:
npm install -g qtm4j-mcp-server
Then in your client config, replace the npx command:
{
"mcpServers": {
"qtm4j": {
"command": "qtm4j-mcp-server",
"env": {
"QTM4J_API_KEY": "your-api-key-here",
"QTM4J_REGION": "US"
}
}
}
}
Tradeoff: instant startup and works offline, but you'll need to run npm update -g qtm4j-mcp-server to get new versions.
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
QTM4J_API_KEY | yes | β | QMetry API key, sent on every request as the apiKey header |
QTM4J_REGION | no | US | US β https://qtmcloud.qmetry.com, AU β https://syd-qtmcloud.qmetry.com |
π‘ Set
QTM4J_REGION=AUif your QMetry instance is on the Sydney cluster.
Tools
All tools are prefixed with qtm4j_ to avoid collisions with other MCP servers.
| Area | Tools |
|---|---|
| Test Cases | qtm4j_create_test_case, qtm4j_get_test_case, qtm4j_search_test_cases, qtm4j_update_test_case, qtm4j_delete_test_case, qtm4j_clone_test_cases, qtm4j_create_test_steps, qtm4j_update_test_steps |
| Test Cycles | qtm4j_create_test_cycle, qtm4j_get_test_cycle, qtm4j_search_test_cycles, qtm4j_update_test_cycle, qtm4j_delete_test_cycle |
| Test Executions | qtm4j_get_test_cycle_executions, qtm4j_update_test_execution, qtm4j_update_test_step_execution, qtm4j_bulk_update_test_executions |
| Test Plans | qtm4j_create_test_plan, qtm4j_get_test_plan, qtm4j_search_test_plans, qtm4j_update_test_plan, qtm4j_delete_test_plan, qtm4j_link_test_cycles_to_plan, qtm4j_get_linked_test_cycles, qtm4j_unlink_test_cycles_from_plan |
| Folders | qtm4j_list_folders, qtm4j_create_folder |
| Automation | qtm4j_link_automation_rule, qtm4j_unlink_automation_rule, qtm4j_run_automation_rules |
| Metadata (read-only) | qtm4j_get_projects, qtm4j_get_priorities, qtm4j_get_priority_icons, qtm4j_get_statuses, qtm4j_get_environments, qtm4j_get_builds, qtm4j_get_labels, qtm4j_get_components, qtm4j_get_execution_results, qtm4j_get_custom_fields, qtm4j_get_parameters, qtm4j_get_user_permissions |
See docs/TOOLS.md for the full reference and docs/COOKBOOK.md for example prompts colleagues can paste into any MCP client.
Every tool ships with annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can decide whether to ask for confirmation. Read tools accept a response_format parameter (json default, or markdown for human-readable output). Large responses are automatically truncated at 25k characters with a hint to narrow the query.
All tools validate inputs with Zod, paginate via startAt/maxResults, and automatically retry rate-limited (HTTP 429) responses with exponential back-off (up to 3 attempts).
Trying it out
Once connected, ask your assistant something like:
Search QMetry project
<your project ID>for test cases with status "To Do" and show me the first 5.
The client will call qtm4j_search_test_cases and render the response.
Get all executions in test cycle FS-TR-747 and mark any unexecuted ones as Pass.
Example tool calls
Replace
10011below with your numeric Jira project ID. Find it in the project URL:β¦?projectId=10011&projectKey=FS.
// Search test cases
{
"name": "qtm4j_search_test_cases",
"arguments": {
"projectId": 10011,
"status": ["Approved"],
"maxResults": 20,
"response_format": "markdown"
}
}
// Update an execution result
// (executionResultId: 239444=Pass, 239441=Fail, 239443=Not Executed)
{
"name": "qtm4j_update_test_execution",
"arguments": {
"cycleId": "gxMbioKJsyEr3E",
"testCaseExecutionId": 287595809,
"executionResultId": 239444,
"comment": "Verified on staging"
}
}
Troubleshooting
- Tools don't appear in my client. Restart the client after editing config. Check
claude mcp list(Claude Code) or VS Code's MCP panel for connection status. On first run,npx -y qtm4j-mcp-servermay take a few seconds to download the package. - 401 Unauthorized. Your
QTM4J_API_KEYis invalid or expired. Generate a new one in QMetry β API Keys. - 404 on execution or search endpoints. Many endpoints want the internal numeric
id, not the human key likeFS-TR-747. Callqtm4j_get_test_cyclefirst to translate the key into the internal id. - Empty or oversized folder response. Pass
folderIdtoqtm4j_list_foldersto scope to a subtree β full project trees on large projects can exceed the response size limit. projectIdrejected. Use the numeric Jira project ID (e.g.10011), not the project key ("FS"). You can find it in the Jira project URL:β¦?projectId=10011&projectKey=FS.
Notes
- Search endpoints use
POST /β¦/searchβ filters go in the body underfilter, pagination/sort on the query string. Tool handlers wrap this for you. 204 No Contentresponses resolve as{ message: "β¦" }.- The Swagger spec does not currently document a framework-style automation import-result endpoint (e.g. JUnit/TestNG/Cucumber ingestion); the automation tools cover the rules-run and rule-link flows exposed in the spec.
Development
Local setup if you want to modify the server:
git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build
QTM4J_API_KEY=your-key npm start
Test changes with the MCP Inspector:
QTM4J_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js
Bugs and contributions
Found a bug or want to suggest a feature? Open an issue at https://github.com/salehrifai42/qmetrymcp/issues. PRs welcome.
