qtm4j-mcp-server

QTM4J MCP サーバー

QMetry Test Management for Jira（QTM4J）向けの87 個のツールを備えたMCPサーバーです。Claude Desktop、Claude Code、VS Code Copilot、Cursor、またはMCP対応のクライアントから、テストケース、サイクル、実行、プラン、フォルダー、コメント、不具合、自動化ルール、プロジェクトのメタデータを検索、管理できます。

配布先：

• npm：qtm4j-mcp-server
• MCP Registry：io.github.salehrifai42/qtm4j-mcp-server
• GitHub：salehrifai42/qmetrymcp

クイックスタート（クローン不要）

QMetry API キー（QMetry → API Keys）とNode.js 18以降が必要です。

Claude Desktop

設定ファイルを編集し、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 エージェントモード）

ワークスペースに.vscode/mcp.jsonを作成します：

{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "${env:QTM4J_API_KEY}",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Copilot ChatをAgentモードに切り替えると、qtm4j_*ツールが自動的に表示されます。

Cursor

~/.cursor/mcp.json（プロジェクト単位の場合は<project>/.cursor/mcp.json）に追加します：

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": { "QTM4J_API_KEY": "your-api-key-here" }
    }
  }
}

上記の設定例では、将来の破壊的変更を伴うリリースによって自動アップグレードされないよう、パッケージのバージョンを^0.1に固定しています。常に最新バージョンを実行したい場合は、@^0.1の接尾辞を削除してください。

グローバルインストール（起動を高速化）

npxは起動のたびにパッケージを再解決するため、起動が数秒遅くなります。サーバーを頻繁に使う場合は、グローバルにインストールして、クライアントからバイナリを直接指定してください：

npm install -g qtm4j-mcp-server

次に、クライアントの設定でnpxコマンドを置き換えます：

{
  "mcpServers": {
    "qtm4j": {
      "command": "qtm4j-mcp-server",
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

トレードオフ：すぐに起動でき、オフラインでも動作しますが、新しいバージョンを入手するにはnpm update -g qtm4j-mcp-serverを実行する必要があります。

設定

変数	必須	デフォルト	説明
QTM4J_API_KEY	はい	—	QMetry API キー。すべてのリクエストでapiKeyヘッダーとして送信されます
QTM4J_REGION	いいえ	US	US → https://qtmcloud.qmetry.com、AU → https://syd-qtmcloud.qmetry.com

💡 QMetryインスタンスがシドニークラスターにある場合は、QTM4J_REGION=AUを設定してください。

ツール

他の MCP サーバーとの名前の衝突を避けるため、すべてのツールには qtm4j_ がプレフィックスとして付いています。

分野	ツール
テストケース	qtm4j_create_test_case, qtm4j_get_test_case, qtm4j_search_test_cases, qtm4j_update_test_case, qtm4j_delete_test_case, qtm4j_archive_test_case, qtm4j_unarchive_test_case, qtm4j_clone_test_cases, qtm4j_create_test_steps, qtm4j_update_test_steps
テストサイクル	qtm4j_create_test_cycle, qtm4j_get_test_cycle, qtm4j_search_test_cycles, qtm4j_update_test_cycle, qtm4j_delete_test_cycle, qtm4j_archive_test_cycle, qtm4j_unarchive_test_cycle
テスト実行	qtm4j_get_test_cycle_executions, qtm4j_get_test_execution, qtm4j_update_test_execution, qtm4j_update_test_step_execution, qtm4j_bulk_update_test_executions, qtm4j_get_execution_teststeps, qtm4j_update_execution_custom_fields, qtm4j_upload_execution_attachment, qtm4j_list_execution_attachments, qtm4j_delete_execution_attachment
テスト計画	qtm4j_create_test_plan, qtm4j_get_test_plan, qtm4j_search_test_plans, qtm4j_update_test_plan, qtm4j_delete_test_plan, qtm4j_archive_test_plan, qtm4j_unarchive_test_plan, qtm4j_link_test_cycles_to_plan, qtm4j_get_linked_test_cycles, qtm4j_unlink_test_cycles_from_plan
コメント	qtm4j_get_test_case_comments, qtm4j_add_test_case_comment, qtm4j_update_test_case_comment, qtm4j_delete_test_case_comment, qtm4j_get_test_cycle_comments, qtm4j_add_test_cycle_comment, qtm4j_update_test_cycle_comment, qtm4j_delete_test_cycle_comment, qtm4j_get_test_plan_comments, qtm4j_add_test_plan_comment, qtm4j_update_test_plan_comment, qtm4j_delete_test_plan_comment
不具合	qtm4j_get_execution_defects, qtm4j_link_execution_defects, qtm4j_unlink_execution_defects, qtm4j_get_step_execution_defects, qtm4j_link_step_execution_defects, qtm4j_unlink_step_execution_defects, qtm4j_search_cycle_defects, qtm4j_get_cycle_defect_summary
フォルダー	qtm4j_list_folders, qtm4j_create_folder
自動化	qtm4j_link_automation_rule, qtm4j_unlink_automation_rule, qtm4j_run_automation_rules
メタデータ（読み取り専用）	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

詳細なリファレンスは docs/TOOLS.md、同僚が任意の MCP クライアントに貼り付けて使えるプロンプト例は docs/COOKBOOK.md をご覧ください。

すべてのツールにはアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付属しているため、クライアントは確認を求めるかどうかを判断できます。読み取りツールは response_format パラメーターを受け付けます（デフォルトは json、人が読みやすい出力には markdown を指定します）。大きなレスポンスは、クエリを絞り込むよう促すヒントとともに、25k 文字で自動的に切り詰められます。

すべてのツールは Zod で入力を検証し、startAt／maxResults によるページネーションを行い、レート制限されたレスポンス（HTTP 429）を指数バックオフで自動的に再試行します（最大 3 回）。

試してみる

接続したら、アシスタントに次のように尋ねてみてください。

QMetry プロジェクト <your project ID> で、ステータスが "To Do" のテストケースを検索し、最初の 5 件を表示してください。

クライアントは qtm4j_search_test_cases を呼び出し、レスポンスを表示します。

テストサイクル <KEY>-TR-747 のすべての実行を取得し、未実行のものを Pass にしてください。

ツール呼び出しの例

<projectId> と <KEY> を、テナントの数値 Jira プロジェクト ID とプロジェクトキーに置き換えてください。プロジェクト URL …?projectId=<projectId>&projectKey=<KEY> で確認できます。qtm4j_get_execution_results を使って、テナントの executionResultId の値を確認してください。

// Search test cases
{
  "name": "qtm4j_search_test_cases",
  "arguments": {
    "projectId": "<projectId>",
    "status": ["Approved"],
    "maxResults": 20,
    "response_format": "markdown"
  }
}

// Update an execution result
{
  "name": "qtm4j_update_test_execution",
  "arguments": {
    "cycleId": "<internal-cycle-id>",
    "testCaseExecutionId": "<internal-tc-execution-id>",
    "executionResultId": "<pass-id>",
    "comment": "Verified on staging"
  }
}

トラブルシューティング

• クライアントにツールが表示されません。 設定を編集した後、クライアントを再起動してください。接続状況は、claude mcp list（Claude Code）または VS Code の MCP パネルで確認してください。初回実行時は、npx -y qtm4j-mcp-server によるパッケージのダウンロードに数秒かかることがあります。
• 401 Unauthorized。 QTM4J_API_KEY が無効か、有効期限が切れています。QMetry → API Keys で新しいキーを生成してください。
• 実行または検索エンドポイントで404が発生します。 多くのエンドポイントでは、<KEY>-TR-747 のような人間が読めるキーではなく、内部の数値 id が必要です。まず qtm4j_get_test_cycle を呼び出して、キーを内部 ID に変換してください。
• フォルダーの応答が空、または大きすぎます。 qtm4j_list_folders に folderId を渡して、対象をサブツリーに絞り込んでください。大規模プロジェクトでは、プロジェクト全体のツリーが応答サイズの上限を超えることがあります。
• projectId が拒否されます。 プロジェクトキー文字列ではなく、Jira の数値のプロジェクト ID を使用してください。Jira プロジェクトの URL で確認できます：…?projectId=<numeric-id>&projectKey=<KEY>。

補足

• 検索エンドポイントでは POST /…/search を使用します。フィルターは本文の filter に、ページネーションと並べ替えはクエリ文字列に指定します。ツールハンドラーがこれらを処理します。
• 204 No Content の応答は { message: "…" } として解決されます。
• Swagger 仕様には、現在、フレームワーク形式の自動化インポート結果エンドポイント（JUnit/TestNG/Cucumber の取り込みなど）が記載されていません。自動化ツールで対応しているのは、仕様で公開されているルール実行とルールリンクのフローです。

開発

サーバーを変更する場合のローカルセットアップ：

git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build
QTM4J_API_KEY=your-key npm start

変更内容は MCP Inspector でテストしてください：

QTM4J_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

単体テストを実行します（API キーやネットワークは不要です。HTTP クライアントのトランスポートはメモリ内でフェイク化されています）：

npm test

一括 xlsx インポートワークフローの再現

このリポジトリには、Excel のテストケースフォルダーを QMetry に取り込むための Claude Code スキル（.claude/skills/xlsx-to-qmetry/）と Python インポーター（scripts/import-xlsx-to-qmetry.py）が含まれています。テナント固有の ID（プロジェクト、親フォルダー、ステータス、カスタムフィールド ID、コンポーネント）は Git に含めず、独自の config.json で指定します。

クローン後の初回セットアップ：

cp config.template.json config.json
# Edit config.json — fill in:
#   connection.apiKey         (QMetry → avatar → API Keys → Generate)
#   connection.projectId      (numeric Jira project ID)
#   xlsxImport.parentFolderId (target folder for new test cases)
#   xlsxImport.statusId       (e.g. Draft / Approved)
#   xlsxImport.apiTestFieldId (custom field ID for "API Test" toggle, if used)
#   xlsxImport.options        (Yes/No option IDs for that custom field)
#   xlsxImport.componentIds   (default components to attach; can be [])

cp .claude/commands/qtm4j.template.md .claude/commands/qtm4j.md
# Optional: populate qtm4j.md with your tenant's IDs using the GET endpoints listed inside.

必要な ID は、起動中の MCP サーバー（qtm4j_get_projects、qtm4j_get_statuses、qtm4j_get_components、qtm4j_get_custom_fields、qtm4j_list_folders）または node scripts/refresh-field-reference.mjs を使用して確認し、すべてを field_reference.json に出力できます。

次に、リポジトリのルートから Claude Code を起動すると、xlsx-to-qmetry スキルが自動的に読み込まれます。ワークブックを Input/<batch-name>/ に配置して、Claude にインポートを依頼してください。ワークフロー全体については、docs/EXCEL-IMPORT-GUIDE.md を参照してください。

バグ報告とコントリビューション

バグを見つけた場合や機能を提案したい場合は、https://github.com/salehrifai42/qmetrymcp/issues で issue を作成してください。プルリクエストも歓迎します。

ライセンス

MIT