Testrail Mcp Server

対応製品：

📚 ドキュメント · はじめに · ツールリファレンス · よくある質問

TestRail MCP サーバーとは？

TestRail MCP Server は、無料のオープンソース Model Context Protocol サーバーです。TestRail API v2 を通じて、AI アシスタントが TestRail インスタンスに直接、構造化された形でアクセスできるようにします。設定すると、Claude Desktop、Cursor、Windsurf、または VS Code の GitHub Copilot などのアシスタントが、チャットウィンドウから離れることなく、テストケースの検索、新規テストケースの作成、テストランの開始、結果の記録、添付ファイルのアップロードを代行できます。

35 個のツールを公開し、MCP stdio トランスポート経由で Node.js 18+ 上でローカル実行され、ライセンスは Apache 2.0 です。ホストやデプロイは不要です。MCP クライアントが必要に応じて npx で起動します。

コンテキストの切り替えは不要です。面倒なコピー＆ペーストも不要です。AI に尋ねるだけです。

メモ

互換性の基準：TestRail 10.6.2（API v2）でテストおよび検証済みです。古い TestRail インスタンス（7.x より前のページネーションを含む）も、組み込みの後方互換性によってサポートされます。TestRail Cloud とセルフホスト型の TestRail Server の両方で動作します。

目次

• 主な機能
• クイックスタート
• コマンドラインインターフェースと CI/CD
• 環境変数
• 利用可能なツール
• よくある質問
• ドキュメント
• コントリビューション

✨ 主な機能

🚀 クイックスタートガイド

1. TestRail API キーを取得する

TestRail の My Settings → API Keys に移動して、新しいキーを生成します。キーはすぐにコピーしてください。TestRail で表示されるのは一度だけです。また、Administration → Site Settings → API で、インスタンス全体の API を有効にする必要があります。

2. MCP クライアントを設定する

MCP クライアントの設定にサーバーを追加します。以下に Claude Desktop の例を示します。Cursor、Windsurf、VS Code も同じ形式です（折りたたみセクションを参照）。

🤖 Claude Desktop

claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key",
        "TESTRAIL_ENABLE_SHARED_STEPS": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "testrail-api-key",
      "type": "promptString",
      "description": "TestRail API key",
      "password": true
    }
  ],
  "servers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@uarlouski/testrail-mcp-server@latest"],
      "env": {
        "TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "[email protected]",
        "TESTRAIL_API_KEY": "${input:testrail-api-key}"
      }
    }
  }
}

クライアントを完全に再起動してから、AI アシスタントに次のように尋ねて、QA ワークフローを大幅に効率化しましょう。

• 「TestRail のすべてのプロジェクトを一覧表示して、最新のアクティブなプロジェクトを見つけてください。」
• 「プロジェクト内のアクティブなユーザーをすべて表示して、適切な担当者を見つけてください。」
• 「プロジェクト 3 のセクション 5 にあるすべてのテストケースを表示してください。」
• 「『Login Validation』の包括的なテストケースを、詳細な手順とともに作成してください。」
• 「セクション 5 のケースを含む新しいテストランを開始してください。」
• 「テストケース C1042 を合格としてマークし、『staging で検証済み』というコメントを追加してください。」

トラブルシューティングを含む、クライアントごとのセットアップ手順については、Getting Started ガイドをご覧ください。

🖥️ コマンドラインインターフェース（CLI）と CI/CD 自動化

AI アシスタントを介した操作に加えて、testrail-cli または npx を使用し、LLM によるオーバーヘッドなしで、シェルスクリプト、ターミナル環境、自動化された CI/CD パイプライン（GitHub Actions、GitLab CI、Jenkins）から TestRail の任意のツールを直接呼び出せます。

• 決定論的な実行：標準的な Unix の終了コード（成功時は 0、エラー時は 1）を返します。
• パイプラインに適した出力：jq などのツールにパイプできる、整形済みの JSON を stdout に出力します。診断情報とエラーは stderr に出力されます。
• 重複なし：MCP サーバーとまったく同じ API クライアント、再試行ロジック、検証スキーマを再利用します。

呼び出し方法

# Method 1: Direct npx subcommand (Recommended)
npx @uarlouski/testrail-mcp-server cli <command> [flags]

# Method 2: Global or local binary
testrail-cli <command> [flags]

# Method 3: Via package runner
npx -p @uarlouski/testrail-mcp-server testrail-cli <command> [flags]

例

プロジェクトを検索する（query_project）

# List all active projects
npx @uarlouski/testrail-mcp-server cli query_project --action many

# Query a single project by ID
npx @uarlouski/testrail-mcp-server cli query_project --action one --project_id 1

自動テストの結果を報告する（add_results_for_cases）

# Submit results by case_id — what your test framework already knows
npx @uarlouski/testrail-mcp-server cli add_results_for_cases \
  --run_id 88 \
  --results '[{"case_id":1042,"status_id":1,"comment":"Passed in CI"}]'

ナレッジベース／RAG 用にケースをエクスポートする（export_cases_for_rag）

# Export all cases for a project into Markdown & metadata sidecars
npx @uarlouski/testrail-mcp-server cli export_cases_for_rag \
  --project_id 1 \
  --output_dir ./rag_exports

# Export specific cases by ID (comma-separated list)
npx @uarlouski/testrail-mcp-server cli export_cases_for_rag \
  --case_ids C101,C102,103 \
  --output_dir ./rag_exports

コマンドの検索とフラグのドキュメント

# List all available commands
npx @uarlouski/testrail-mcp-server cli --help

# Show parameter options for a specific tool
npx @uarlouski/testrail-mcp-server cli query_project --help

GitHub Actions、GitLab CI、Jenkins のワークフロー全般については、CLI と CI/CD のガイドをご覧ください。

⚙️ 環境変数とセキュリティ制御

必須の認証情報を 3 つだけ設定した場合、35 個のツールのうち 27 個が登録されます。すぐに利用できる読み取り専用および最小権限の設定については、設定ガイドをご覧ください。

🧰 利用可能なツール

全35個のツールを領域ごとに分類しています。それぞれに read、write、delete のいずれかのモードが設定されており、サーバーはこれを MCP アノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）としてクライアントに公開します。

❓ よくある質問

詳しくはFAQ 全文をご覧ください。

📚 ドキュメントとツールの完全なリファレンス

包括的なガイド、詳細な設定オプション、利用可能なすべてのツールの完全な説明については、公式ドキュメントサイトをご覧ください。

👉 TestRail MCP Server のドキュメント

• 🚀 はじめに：Claude、Cursor、Windsurf、VS Code のクライアントごとのセットアップ。
• ⚙️ 設定：すべての環境変数、権限、機能フラグ。
• 🧰 すべてのツール：35 個のツールすべてを、モードや機能フラグとともに 1 つの表にまとめています。
• 🔭 探索とナビゲーション：プロジェクト、スイート、セクションの探索。
• 📋 テストケース管理：テストケースの取得、作成、一括更新。
• ▶️ 実行と追跡：テストランの管理とテスト結果の送信。
• 📎 添付ファイル：ファイルやディレクトリの自動圧縮とアップロード。
• 🔗 共有ステップ：再利用可能なステップ定義の管理。
• 🖥️ CLI と CI/CD：LLM を使わないパイプラインの自動化。

🤝 貢献

オープンソースへの貢献を歓迎します！機能のリクエストについては、issue を作成するか、改善のためのプルリクエストをお送りください。

📜 ライセンス

このプロジェクトは Apache License 2.0 のライセンスに基づいています。

TestRail MCP Server · Model Context Protocol を使用して構築