Jira QMetry MCP Server

🌐 Language: English | Español

MCP (Model Context Protocol) server to interact with the QMetry for Jira API. Allows large language models (LLMs) and client applications to access QMetry test management functionalities through well-defined tools.

📋 Project Description

This project implements a server based on the Model Context Protocol (MCP) that provides a complete interface to manage test cases, test cycles, test plans, and their associated configurations in QMetry. The server is built with TypeScript and uses the official MCP SDK.

Key Features

• ✅ Complete Test Case Management: Create, search, edit, move, and copy test cases
• ✅ Test Steps Management: Create, update, delete, and retrieve test steps
• ✅ Folder Organization: Manage folders for test cases, test cycles, and test plans
• ✅ Status Configuration: Manage custom statuses for test cases, test cycles, and test plans
• ✅ Priority Management: Full CRUD of priorities with custom colors
• ✅ Label System: Create, update, and delete labels for organization
• ✅ Linked Requirements: Link and unlink requirements (Jira issues) with test cases
• ✅ Custom Fields: Support for custom fields in test cases, test cycles, test plans, and test executions
• ✅ Robust Architecture: Logging system, error handling, and schema validation with Zod

🏗️ Project Structure

jira-qmetry-mcp/
├── src/
│   ├── api/                          # QMetry API call functions
│   │   ├── qmetry-projects.ts
│   │   ├── qmetry-test-case.ts
│   │   ├── qmetry-test-case-folders.ts
│   │   ├── qmetry-test-case-status.ts
│   │   ├── qmetry-test-cycle-folders.ts
│   │   ├── qmetry-test-cycle-status.ts
│   │   ├── qmetry-test-plan-folders.ts
│   │   ├── qmetry-test-plan-status.ts
│   │   ├── qmetry-test-steps.ts
│   │   ├── qmetry-priorities.ts
│   │   ├── qmetry-labels.ts
│   │   ├── qmetry-components.ts
│   │   ├── qmetry-linked-requirements.ts
│   │   ├── qmetry-custom-fields.ts
│   │   └── qmetry-test-cycle-executions.ts
│   ├── interfaces/                   # TypeScript type definitions
│   │   ├── qmetry-projects.ts
│   │   ├── qmetry-test-cases.ts
│   │   ├── qmetry-test-case-folders.ts
│   │   ├── qmetry-test-cycle-folders.ts
│   │   ├── qmetry-test-plan-folders.ts
│   │   ├── qmetry-test-steps.ts
│   │   ├── qmetry-priorities.ts
│   │   ├── qmetry-labels.ts
│   │   ├── qmetry-status.ts
│   │   ├── qmetry-linked-requirements.ts
│   │   ├── qmetry-custom-fields.ts
│   │   ├── qmetry-test-cycle-executions.ts
│   │   ├── toolDefinition.ts
│   │   └── index.ts
│   ├── tools/                        # MCP tool definitions
│   │   ├── project-tools.ts
│   │   ├── test-cases-tools.ts
│   │   ├── test-case-folder-tools.ts
│   │   ├── test-cases-status-tools.ts
│   │   ├── test-cycle-folder-tools.ts
│   │   ├── test-cycle-status-tools.ts
│   │   ├── test-plan-folder-tools.ts
│   │   ├── test-plan-status-tools.ts
│   │   ├── test-step-tools.ts
│   │   ├── priority-tools.ts
│   │   ├── label-tools.ts
│   │   ├── linked-requirements-tools.ts
│   │   ├── custom-field-tools.ts
│   │   └── test-cycle-execution-tools.ts
│   ├── utils/                        # Utilities and helpers
│   │   ├── logger.ts
│   │   ├── object.utils.ts
│   │   └── index.ts
│   ├── main.ts                       # MCP server entry point (stdio)
│   ├── http-server.ts                # HTTP server with Streamable HTTP transport
│   └── config.json                   # API configuration
├── package.json
├── tsconfig.json
├── eslint.config.js
├── LICENSE
├── NOTICE
├── CONTRIBUTING.md
└── README.md

🔧 Setup

1. Install Dependencies

pnpm install

2. Environment Variable

Configure your QMetry API key:

export QMETRY_API_KEY="your-api-key-here"

💡 Note: The API key is generated from the Jira interface: QMetry > Configuration > Open API > Generate

3. Run the Server

Option A: Local Development

pnpm start

To use the MCP inspector:

pnpm run:inspector

Option B: Docker Deployment

The project includes a simple Dockerfile that works with any platform (Railway, Dokploy, Render, etc.).

Using Docker directly:

# Build the image
docker build -t jira-qmetry-mcp .

# Run the container (port is configurable)
docker run -d \
  --name jira-qmetry-mcp \
  -p 3000:3000 \
  -e PORT=3000 \
  -e QMETRY_API_KEY="your-api-key-here" \
  jira-qmetry-mcp

# View logs
docker logs -f jira-qmetry-mcp

Using Docker Compose (for local development):

# Create .env file with your configuration
cp .env.example .env
# Edit .env and add your QMETRY_API_KEY

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

Deploying to Railway/Dokploy/Render:

These platforms will automatically detect the Dockerfile. Just set the environment variables:

• PORT - Will be set automatically by the platform (or use 3000)
• QMETRY_API_KEY - Your QMetry API key (required)
• NODE_ENV - Set to production (optional, defaults to production)

🛠️ Available Tools

📁 Projects

Tool: list-qmetry-projects

• Get projects: List all QMetry-enabled projects with filtering and pagination

📝 Test Cases

Tools: get-qmetry-test-cases, create-qmetry-test-case, move-qmetry-test-case, copy-qmetry-test-case, update-qmetry-test-case

• Get: Search test cases with advanced filters (assignee, status, labels, etc.)
• Create: Create new test cases with steps, descriptions, and configurations
• Move: Move test cases between folders
• Copy: Copy test cases to different locations
• Update: Update test case information

🔄 Test Case Versions

Tools: get-test-case-version-details, add-test-case-version, delete-test-case-version, get-test-case-versions-list

• Get version details: Retrieve specific version information
• Add version: Create new version from existing version
• Delete version: Remove a specific version
• Get versions list: View all versions of a test case

📦 Test Case Lifecycle

Tools: archive-qmetry-test-case, unarchive-qmetry-test-case, clone-qmetry-test-case, get-test-case-test-cycles

• Archive: Archive a test case
• Unarchive: Restore archived test case
• Clone: Duplicate test case with options
• Get linked cycles: View test cycles linked to a test case

📂 Test Case Folders

Tools: get-qmetry-test-case-folders, create-qmetry-test-case-folder, edit-qmetry-test-case-folder, copy-qmetry-test-case-folder, move-qmetry-test-case-folder, search-qmetry-test-case-folders

• Get: List all test case folders in a project
• Create: Create new folders with parent-child hierarchy
• Edit: Modify name and description of existing folders
• Copy: Copy folders to new locations
• Move: Move folders to different parent folders
• Search: Search folders by name (strict or relative mode)

🎯 Test Case Status

Tools: get-qmetry-test-case-statuses, create-qmetry-test-case-status, update-qmetry-test-case-status, delete-qmetry-test-case-status, get-test-case-status-ref-count

• Get: List all test case statuses (active/archived)
• Create: Create custom statuses with colors
• Update: Modify existing statuses
• Delete: Remove statuses from project
• Reference count: Check how many cases use a specific status

🔄 Test Cycles

Tools: search-qmetry-test-cycles, create-qmetry-test-cycle, update-qmetry-test-cycle, move-qmetry-test-cycle, link-test-case-to-test-cycle, unlink-test-case-from-test-cycle, get-test-cycle-test-plans, link-requirements-to-test-cycle, unlink-requirements-from-test-cycle, archive-qmetry-test-cycle, unarchive-qmetry-test-cycle

• Search: Search and filter test cycles with advanced criteria
• Create: Create new test cycles with configuration
• Update: Modify existing test cycles
• Move: Move test cycles to different folders
• Link/Unlink test cases: Associate or remove test cases from a cycle
• Get linked test plans: View test plans linked to a test cycle
• Link/Unlink requirements: Manage Jira requirements linked to cycles
• Archive: Archive or unarchive test cycles

🔄 Test Cycle Execution

Tools: get-qmetry-test-cycle-linked-test-cases, get-qmetry-test-cycle-linked-defects

• Get linked test cases: Retrieve all test cases linked to a specific test cycle with advanced filtering
  • Filter by: searchText, status, priority, testCaseKey, environment, executionResult, build, removeDuplicates, linkedBetweenDates, executionLevel
  • Supports pagination, field selection, and sorting
• Get linked defects: Retrieve all defects linked to test cycle executions
  • Filter by: searchText, status, priority, testCaseKey, environment, executionResult, build, removeDuplicates, linkedBetweenDates, executionLevel
  • Supports pagination, field selection, and sorting

🔄 Test Cycle Status

Tools: get-qmetry-test-cycle-statuses, create-qmetry-test-cycle-status, update-qmetry-test-cycle-status, delete-qmetry-test-cycle-status, get-test-cycle-status-ref-count

• Get: List test cycle statuses
• Create: Create custom statuses for cycles
• Update: Modify existing statuses
• Delete: Remove unused statuses
• Reference count: Check status usage

📋 Test Plans

Tools: search-qmetry-test-plans, get-qmetry-test-plan, create-qmetry-test-plan, update-qmetry-test-plan, move-qmetry-test-plans, get-test-plan-test-cycles, link-test-cycles-to-test-plan, unlink-test-cycles-from-test-plan, archive-qmetry-test-plan, unarchive-qmetry-test-plan

• Search: Search and filter test plans
• Get: Retrieve specific test plan details
• Create: Create new test plans
• Update: Modify existing test plans
• Move: Move test plans to different folders
• Get linked test cycles: View test cycles linked to a plan
• Link/Unlink test cycles: Associate or remove test cycles from plans
• Archive: Archive or unarchive test plans

📋 Test Plan Status

Tools: get-qmetry-test-plan-statuses, create-qmetry-test-plan-status, update-qmetry-test-plan-status, delete-qmetry-test-plan-status, get-test-plan-status-ref-count

• Get: List test plan statuses
• Create: Create custom statuses
• Update: Modify existing statuses
• Delete: Remove statuses from project
• Reference count: View status usage

🪜 Test Steps

Tools: get-qmetry-test-steps, create-qmetry-test-step, update-qmetry-test-step, delete-qmetry-test-step

• Get: List all steps of a test case with pagination
• Create: Create multiple steps with details, test data, and expected results
• Update: Modify existing steps
• Delete: Remove steps from a test case

⚡ Priorities

Tools: get-qmetry-priorities, create-qmetry-priority, update-qmetry-priority, delete-qmetry-priority, search-qmetry-priorities

• Get: List all project priorities
• Create: Create custom priorities with hexadecimal colors
• Update: Modify existing priorities
• Delete: Remove unused priorities
• Search: Locate priorities by name

🏷️ Labels

Tools: get-qmetry-labels, create-qmetry-label, update-qmetry-label, delete-qmetry-label, get-qmetry-label-reference-count

• Get: List all project labels
• Create: Create new labels for categorization
• Update: Modify label names
• Delete: Remove labels from project
• Reference count: See how many items use a label

🔗 Linked Requirements

Tools: get-qmetry-linked-requirements, link-qmetry-requirements, unlink-qmetry-requirements

• Get: List all requirements (Jira issues) linked to a test case
• Link: Associate one or more Jira issues with a test case
• Unlink: Remove association between requirements and test cases

🏷️ Custom Fields

Tools: get-qmetry-custom-field-types, get-qmetry-test-case-custom-fields, get-tc-custom-field-ref-count, get-qmetry-test-cycle-custom-fields, get-tcy-custom-field-ref-count, get-qmetry-test-plan-custom-fields, get-tp-custom-field-ref-count, get-qmetry-te-custom-fields, get-te-custom-field-ref-count

Custom Fields in Test Cases, Cycles & Plans:

• Add/filter by custom fields when: creating, updating, searching test cases, test cycles, and test plans
• Custom fields structure: [{ id: string; value: string }]

Get Custom Field Types: List all available custom field types in QMetry

Get Custom Fields by Module:

• Test Case: get-qmetry-test-case-custom-fields - Get all test case custom field details
• Test Cycle: get-qmetry-test-cycle-custom-fields - Get all test cycle custom field details
• Test Plan: get-qmetry-test-plan-custom-fields - Get all test plan custom field details
• Test Execution: get-qmetry-te-custom-fields - Get all test execution custom field details

Reference Counts: Check how many items reference each custom field:

• get-tc-custom-field-ref-count - Test case references
• get-tcy-custom-field-ref-count - Test cycle references
• get-tp-custom-field-ref-count - Test plan references
• get-te-custom-field-ref-count - Test execution references

🚨 Troubleshooting

Error: QMETRY_API_KEY not configured

export QMETRY_API_KEY="your-api-key"

📚 Resources

• Official MCP Documentation
• QMetry for Jira API
• TypeScript Handbook
• Zod Documentation

📄 License

This project is licensed under Apache License 2.0. See the LICENSE file for details.

Why Apache License 2.0?

• ✅ Patent protection: Explicit grant of patent rights
• ✅ Trademark control: Protection over trademark usage
• ✅ Change declaration: Requires documenting modifications
• ✅ Enterprise use: Widely accepted in corporate environments
• ✅ Compatible: With most open source licenses

Important Notices

This software integrates with QMetry and Jira through their public APIs. QMetry is a registered trademark of Zoho Corporation and Jira is a registered trademark of Atlassian Pty Ltd. This project is not affiliated with, endorsed by, or sponsored by these companies.

See the NOTICE file for complete information about attributions and legal notices.

👥 Contributing

To contribute to the project:

1. Fork & Pull Request: Fork the project and submit your changes via pull requests
2. Clean code: Keep code clean using ESLint and Prettier (pnpm lint:fix)
3. Logging: Use the provided logging system (never console.log)
4. Documentation: Document all functions with JSDoc
5. Patterns: Follow established patterns in the project
6. Testing: Test your changes with MCP Inspector (pnpm run:inspector)
7. License: By contributing, you agree that your code will be licensed under Apache License 2.0
8. Changes: Clearly document what changes you made and why

License Header

Add this header at the beginning of new TypeScript files:

/**
 * Copyright 2025 Alberto Zapata
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

For detailed contribution guidelines, see CONTRIBUTING.md.

🔄 Version

v1.8.3 - Current MCP server version

Release Notes

• ✅ v1.8.3 - Fix SDK compatibility: Downgrade to SDK 1.22.0 to resolve Zod v4 literal extraction bug