Testrail Mcp Server

兼容：

📚 文档 · 快速入门 · 工具参考 · 常见问题

什么是 TestRail MCP 服务？

TestRail MCP 服务 是一个免费的开源 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 个分区的所有测试用例。”
• “为‘登录验证’创建一个详尽的测试用例，并包含详细步骤。”
• “创建一个新的测试运行，其中包含第 5 个分区中的用例。”
• “将测试用例 C1042 标记为通过，并添加评论‘已在预发布环境验证’。”

各客户端的完整设置说明（包括故障排除）请参阅入门指南。

🖥️ 命令行界面（CLI）与 CI/CD 自动化

除了通过 AI 助手交互，你还可以使用 testrail-cli 或 npx，直接从 Shell 脚本、终端环境和自动化 CI/CD 流水线（GitHub Actions、GitLab CI、Jenkins）调用任何 TestRail 工具，完全无需 LLM 开销。

• 确定性执行：返回标准 Unix 退出代码（成功时为 0，出错时为 1）。
• 原生支持流水线的输出：向 stdout 输出简洁的 JSON，可通过管道传递给 jq 等工具；诊断信息和错误则输出到 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 指南。

⚙️ 环境变量与安全控制

仅使用三个必需凭据时，会注册 35 个工具中的 27 个。现成的只读配置和最小权限配置请参阅配置指南。

🧰 可用工具

全部 35 个工具，按领域分组。每个工具都声明了 read、write 或 delete 模式，服务器会将其作为 MCP 注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）提供给客户端。

❓ 常见问题

更多解答请参阅完整常见问题。

📚 文档与完整工具参考

如需完整指南、详细配置选项和所有可用工具的完整说明，请访问官方文档网站：

👉 TestRail MCP 服务文档

• 🚀 快速入门：Claude、Cursor、Windsurf 和 VS Code 的客户端配置。
• ⚙️ 配置：所有环境变量、权限和功能标志。
• 🧰 所有工具：一个表格列出所有 35 个工具及其模式和功能标志。
• 🔭 发现与导航：浏览项目、套件和分区。
• 📋 测试用例管理：获取、创建和批量更新测试用例。
• ▶️ 执行与跟踪：管理测试运行并提交测试结果。
• 📎 附件：自动压缩并上传文件或目录。
• 🔗 共享步骤：管理可重复使用的步骤定义。
• 🖥️ CLI 与 CI/CD：无需大模型即可实现流水线自动化。

🤝 贡献

我们热烈欢迎开源贡献！欢迎提交 问题 以申请功能，或提交拉取请求来改进项目。

📜 许可证

本项目采用 Apache License 2.0 许可。

TestRail MCP Server · 基于 Model Context Protocol 构建