Testomatio MCP Server

Testomat.io MCP Server

AI アシスタント（Claude、Cursor、OpenCode など）が Testomat.io Public API v2 と連携できるようにする Model Context Protocol（MCP）サーバーです。

特長

• エンティティごとに 1 つの CLI スタイルのツール - tests、suites、runs、testruns、plans、rungroups、steps、snippets、labels、requirements、branches、tags、milestones、issues。それぞれが command 引数（list、get、create、update、delete と、該当する場合はスコープ付きの issues_*／attachments_*／share コマンド）と、フラットなコマンドパラメーターを受け取ります
• プロジェクト情報 - プロジェクトの設定、メタデータ、機能、CI プロファイルを取得します
• 課題の紐付け - 課題を任意のリソースに紐付け／紐付け解除します（各エンティティの issues_* コマンドとグローバルな issues ツールを使用）
• 添付ファイル - テスト、スイート、テスト実行で attachments_* コマンドを使用できます。アップロード時には、ローカルファイルパスを files マルチパートフィールドとして送信します
• 要件 - ローカルファイルパスからのファイルアップロードに対応しています
• API 互換性 - ペイロード形式の違い（フラット形式とラップ形式）を自動的に処理します
• API セッションの自動管理 - API セッションを使用して、MCP による変更を Testomat.io の履歴でグループ化します
• 実行管理 - status_event パラメーターでステータスを遷移させます
• TQL のみの検索 - tests／runs の command: "list" では、検索／フィルター入力として tql のみを使用します
• 組み込みの TQL リファレンス - TQL パラメーターには、正確なフィールドの許可リストと例が含まれています。tql_help で必要に応じて構文の詳細を確認できます
• ツール構成プロファイル - --tools full|core|read（デフォルトは full）を指定して、セッションに必要なツールのみを公開できます。長時間のエージェントセッションで、呼び出しごとのスキーマコストを削減します

クイックスタート

インストール

npm install -g @testomatio/mcp@latest

エンタープライズ分析ツールが必要ですか？代わりに @testomatio/mcp-enterprise@latest をインストールしてください。詳しくは、以下の Enterprise Analytics セクションを参照してください。

設定

必須の認証情報：

• TESTOMATIO_PROJECT_TOKEN - プロジェクト API トークン
• TESTOMATIO_PROJECT_ID - プロジェクト ID

サーバーを起動：

npx testomatio-mcp --token <PROJECT_TOKEN> --project <PROJECT_ID>

または環境変数を使用：

export TESTOMATIO_PROJECT_TOKEN=<PROJECT_TOKEN>
export TESTOMATIO_PROJECT_ID=<PROJECT_ID>
npx testomatio-mcp

ホスト名のみを指定すると、https://<host> に展開されます。細かく制御するには --base-url／TESTOMATIO_BASE_URL を使用してください。ホストオプションより優先されます。

任意：ツール構成プロファイル

デフォルトでは、サーバーはすべてのツールを公開します。トークンの使用量が気になる長時間のセッションでは、--tools を指定して公開するツールを絞り込めます。

npx testomatio-mcp --token <PROJECT_TOKEN> --project <PROJECT_ID> --tools core

プロファイル	公開される内容
full（デフォルト）	すべて
core	すべてのコマンドを備えたコアエンティティ（steps、snippets、labels、rungroups ツールを除く）
read	読み取り専用コマンド（list、get、search、issues_list、attachments_list）に制限されたコアエンティティ

値は大文字と小文字を区別しません。不明な値を指定すると、サーバーは起動しません。起動時にフラグまたは TESTOMATIO_TOOLS 環境変数でプロファイルを設定してください。セッション中に変更することはできません。両方が設定されている場合は、CLI フラグが優先されます。

AI アシスタントでの使用

Cursor IDE

この設定を、プロジェクト内の .cursor/mcp.json またはグローバルに使用する場合は ~/.cursor/mcp.json に追加してください。

{
  "mcpServers": {
    "testomatio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@testomatio/mcp@latest",
        "--token",
        "<TOKEN>",
        "--project",
        "<PROJECT_ID>"
      ],
      "env": {
        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
      }
    }
  }
}

Claude Desktop

この設定を次のファイルに追加してください。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "testomatio": {
      "command": "npx",
      "args": [
        "-y",
        "@testomatio/mcp@latest",
        "--token",
        "<TOKEN>",
        "--project",
        "<PROJECT_ID>"
      ],
      "env": {
        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
      }
    }
  }
}

OpenCode

この設定を、プロジェクトのルートにある opencode.json またはグローバルに使用する場合は ~/.config/opencode/opencode.json に追加してください。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "testomat": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@testomatio/mcp@latest",
        "--token",
        "<TOKEN>",
        "--project",
        "<PROJECT_ID>"
      ],
      "enabled": true,
      "environment": {
        "TESTOMATIO_BASE_URL": "https://app.testomat.io"
      }
    }
  }
}

HTTP トランスポート

stdio に加えて、サーバーは Testomat.io がホストする Cloudflare Worker 上で Streamable HTTP を使用して動作します。URL にはプロジェクトが含まれるため、すべてのツールのシグネチャは変わりません。

https://mcp.testomat.io/mcp/<project_id>

プロジェクトトークンを使って、その URL を MCP クライアントに設定します。

{
  "mcpServers": {
    "testomatio": {
      "url": "https://mcp.testomat.io/mcp/<PROJECT_ID>",
      "headers": {
        "Authorization": "Bearer <PROJECT_TOKEN>"
      }
    }
  }
}

claude.ai などの Web コネクターでは静的トークンを設定する場所がないため、同じ URL に対して PKCE と Dynamic Client Registration を使用した OAuth 2.1 を実行します。testomat_ または tstmt_ で始まるトークンは常に OAuth をバイパスしてそのまま渡されるため、IDE クライアントと CI は引き続き動作します。

エンドポイントは POST のみを受け付けます。サーバーがトラフィックを開始することはないため、GET は 405 を返します。curl でテストする場合は、Accept に両方のメディアタイプが必要です。

curl -sS https://mcp.testomat.io/mcp/<PROJECT_ID> \
  -H "Authorization: Bearer <PROJECT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

セルフホスト型のインストールでは、引き続き stdio を使用します。

クイック例

すべてのエンティティツールは CLI のように動作します。command と、そのコマンドに必要なパラメーターを渡します。ツールスキーマ内の各パラメーターの説明には、適用されるコマンドが記載されています。

テストの一覧表示：

{
  "name": "tests",
  "arguments": { "command": "list", "page": 1, "per_page": 50, "tql": "priority == 'high'" }
}

テストの作成：

{
  "name": "tests",
  "arguments": {
    "command": "create",
    "title": "User login test",
    "suite_id": "123",
    "priority": "high"
  }
}

ランの作成：

{
  "name": "runs",
  "arguments": {
    "command": "create",
    "title": "Smoke tests",
    "kind": "automated",
    "env": "production"
  }
}

ランの終了：

{
  "name": "runs",
  "arguments": {
    "command": "update",
    "run_id": "456",
    "status_event": "finish"
  }
}

テストへの添付ファイルのアップロード：

{
  "name": "tests",
  "arguments": {
    "command": "attachments_upload",
    "test_id": "123",
    "file_path": "/path/to/screenshot.png"
  }
}

Markdown からのテストの一括作成／更新：

{
  "name": "tests",
  "arguments": {
    "command": "bulk_upsert",
    "markdown": "\n# Login Functionality\n\n# Successful Login\n\n# Failed Login"
  }
}

id: @T... のあるテストは更新され、ないテストは作成されます。スイートは id: @S... またはタイトルで解決され、見つからない場合は作成されます。1 回の呼び出しで最大 100 件のテストを処理できます。詳しい動作については、docs/tools.md を参照してください。

ドキュメント

ツールの完全なリファレンス：docs/tools.md

プロジェクト構成

src/
|- config/          # Config loading, defaults
|- core/            # Errors, logger
|- api/             # HTTP client, Testomat.io API client
|- mcp/             # MCP server, tools, registry
|  |- definitions/  # Tool definitions by entity
|  |- configs/      # Registry generation configs
|  `- registry/     # Tool handlers
`- cli/             # CLI bootstrap

環境変数

変数	必須	デフォルト	説明
TESTOMATIO_PROJECT_TOKEN	はい*	-	プロジェクトトークン（推奨）
TESTOMATIO_API_TOKEN	はい*	-	代替トークン
TESTOMATIO_PROJECT_ID	はい	-	プロジェクト ID
TESTOMATIO_HOST	いいえ	-	API ホスト。例：beta.testomat.io
TESTOMATIO_BASE_URL	いいえ	https://app.testomat.io	API ベース URL。TESTOMATIO_HOST より優先されます
TESTOMATIO_TOOLS	いいえ	full	ツールプロファイル：full、core、または read

*TESTOMATIO_PROJECT_TOKEN または TESTOMATIO_API_TOKEN のいずれか

企業 TLS 証明書

MCP サーバーが企業プロキシまたは TLS 検査の背後で実行されている場合、同じ URL がブラウザーでは動作しても、Node.js が Testomat.io への HTTPS リクエストを拒否することがあります。通常、これは会社のルート証明書がオペレーティングシステムでは信頼されているものの、Node.js では信頼されていないことを意味します。

Node.js のシステム CA サポートを使用します。

NODE_OPTIONS=--use-system-ca testomatio-mcp --token <TOKEN> --project <PROJECT_ID>

MCP クライアントでは、サーバー環境に NODE_OPTIONS を渡します。

{
  "mcpServers": {
    "testomatio": {
      "command": "testomatio-mcp",
      "args": ["--token", "<TOKEN>", "--project", "<PROJECT_ID>"],
      "env": {
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

お使いの Node.js バージョンが --use-system-ca をサポートしていない場合は、会社のルート証明書を PEM ファイルにエクスポートし、Node.js の追加 CA サポートを使用します。

NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token <TOKEN> --project <PROJECT_ID>

重要な注意事項

• CLI スタイルのツール - エンティティごとにツールが 1 つあり、すべての操作は command 引数で指定します（以前の tests_list ではなく、tests + command: "list" を使用します）。不明なコマンドを指定すると、有効なコマンドを列挙したエラーが返されます
• 実行ステータス - 遷移（完了、起動、再実行など）には、command: "update" と status_event を指定して runs を使用します
• 検索／フィルター - 専用の /search エンドポイントはありません。フィルタリングは list コマンドで行います（tests と runs では tql、その他のエンティティでは OpenAPI に準拠したフィルターを使用します）
• 簡潔なリストレスポンス - リストコマンドはデフォルトでコンパクトな API レスポンスを要求し、サイズの大きいエンティティフィールドと null 値を省略します。完全なオブジェクトを返すには verbose: true を渡すか、選択したフィールドのみを返すには fields: ["id", "title", "description"] を渡します。どちらのオプションもバックエンドへの slim=true リクエストを無効にするため、要求時にはサイズの大きいフィールドも利用できます
• TQL - command: "list" を指定した tests／runs では、検索／フィルター入力として tql のみを使用します
• TQL の構文 - ユーザー向けの構文の詳細とその他の例については、公式の TQL ドキュメントをご覧ください：https://docs.testomat.io/advanced/tql/
• TQL の範囲 - TQL パラメーターの説明には、ドキュメントに記載されたフィールドの許可リストが含まれます。構文の詳細と追加の例については、tql_help を呼び出してください
• 課題のリンク - 各エンティティで利用できるスコープ付きコマンド：command: "issues_link"／"issues_unlink"
• 添付ファイル - tests、suites、testruns で利用できるスコープ付きコマンド：command: "attachments_list" | "attachments_upload" | "attachments_delete"。アップロードでは、ローカルのファイルパスを 1 つ、multipart フィールド files として送信します
• Enterprise パッケージ - 分析ツールは意図的に標準の @testomatio/mcp パッケージではなく、@testomatio/mcp-enterprise でのみ公開されています
• API セッション - サーバーは最初の POST、PUT、または DELETE リクエストの前に Testomat.io セッションを自動的に開始し、返されたセッションハッシュを後続の変更リクエストで X-Session-Hash として送信します。MCP サーバーのシャットダウン時にセッションを終了します。GET リクエストではセッションを開始せず、使用もしません

開発

npm install
npm run start -- --token <TOKEN> --project <PROJECT_ID>
npm test

ローカルで MCP を開発する場合は、チェックアウトしたエントリーポイントを Claude Desktop に指定します。

{
  "mcpServers": {
    "testomatio-local": {
      "command": "node",
      "args": ["/path/to/mcp/index.js", "--token", "<TOKEN>", "--project", "<PROJECT_ID>"]
    }
  }
}

Enterprise 分析

Enterprise 分析は、別個の @testomatio/mcp-enterprise パッケージでのみ利用できます。

インストール：

npm install -g @testomatio/mcp-enterprise@latest

実行：

testomatio-mcp-enterprise --token <PROJECT_TOKEN> --project <PROJECT_ID>

含まれるツール：

• analytics_tests - GET /api/v2/{project_id}/analytics/tests/{kind}
• analytics_stats - GET /api/v2/{project_id}/analytics/stats/{kind}
• analytics_charts_list - GET /api/v2/{project_id}/analytics/charts
• analytics_charts_get - GET /api/v2/{project_id}/analytics/charts/{id}
• analytics_charts_results - GET /api/v2/{project_id}/analytics/charts/{id}/result

分析エンドポイントには api_analytics サブスクリプション機能が必要です。分析ツールの TQL フィルターパラメーターには q を使用します。

analytics_tests の呼び出し例：

{
  "name": "analytics_tests",
  "arguments": {
    "kind": "flaky",
    "q": "priority == 'high'",
    "days": 30,
    "page": 1,
    "per_page": 20
  }
}

analytics_stats の呼び出し例：

{
  "name": "analytics_stats",
  "arguments": {
    "kind": "success-rate-by-date",
    "q": "tag IN ['@smoke']",
    "from": "2026-04-01",
    "to": "2026-04-30"
  }
}

analytics_charts_get は、TQL クエリを含むチャート定義を返します。analytics_charts_results は、クエリごとの合計、または 1 つのクエリに一致する tests／runs（0 から始まる number で指定）を返します。

analytics_charts_results の呼び出し例：

{
  "name": "analytics_charts_results",
  "arguments": {
    "chart_id": "abc123",
    "number": 2,
    "per_page": 50
  }
}