Name: TestRail API管理工具
Author: g-tiwari

使用说明

@g-tiwari/mcp试验轨

MCP服务器 TestRail API为AI助手提供完全访问权限，以管理测试用例、运行、结果、计划和所有其他TestRail资源。

107工具 覆盖每个TestRail API端点，并通过工具集过滤提高令牌效率。

适用于 任何TestRail设置 -标准云/自托管实例（API密钥或密码验证）和企业SSO部署（基于SAML/OIDC cookie-based验证）。

快速开始

添加到您的MCP客户端配置（Claude Desktop、Claude Code、Kiro、Cursor、Windsurf——请参阅 IDE配置在......下面

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

就是这样。重新启动MCP客户端并开始要求它管理TestRail。

企业SSO？ 将API密钥env vars替换为 "TESTRAIL_COOKIE_PATH": "~/path/to/cookies.txt" --看认证对于所有选项。您还可以添加可选的env变量，如 TESTRAIL_PROJECT_IDS, TESTRAIL_TOOLSETS，以及 TESTRAIL_READ_ONLY_MODE 同样的 env 块--参见环境变量.

认证

选项1：API密钥（建议大多数用户使用）

这是TestRail Cloud和自托管实例的标准身份验证方法。

首选 我的设置 在TestRail（右上菜单）中
在下启用API API 部分
生成一个 API密钥

设置这些环境变量：

TESTRAIL_URL=https://yourcompany.testrail.com
TESTRAIL_EMAIL=your@email.com
TESTRAIL_API_KEY=your-api-key

选项2：密码

对于API密钥不可用的情况。

TESTRAIL_URL=https://yourcompany.testrail.com
TESTRAIL_EMAIL=your@email.com
TESTRAIL_PASSWORD=your-password

选项3:SSO Cookie认证（企业）

用于SSO提供程序（Okta、Azure AD等）背后的企业TestRail实例。服务器读取 Netscape格式的cookie文件，自动完成SAML/OIDC登录流程，并获得TestRail会话。

TESTRAIL_URL=https://testrail.yourcompany.com
TESTRAIL_COOKIE_PATH=~/path/to/sso/cookies.txt

它是如何工作的： 服务器从文件加载SSO Cookie，点击TestRail SSO重定向端点，解析SAML响应表单，并将其提交回TestRail以获取 tr_session 饼干。当cookie文件更改时（例如在与SSO提供商重新验证后），它也会热重新加载。

注：您可能需要定期刷新SSO Cookie（例如，通过SSO提供商的CLI重新进行身份验证）。

选项4：SSO Cookie+API密钥（混合）

对于SSO代理需要Cookie的企业设置和 TestRail还验证API密钥验证。

TESTRAIL_URL=https://testrail.yourcompany.com
TESTRAIL_COOKIE_PATH=~/path/to/sso/cookies.txt
TESTRAIL_EMAIL=your@email.com
TESTRAIL_API_KEY=your-api-key

IDE/AI助手配置

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

API密钥授权：

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

SSO Cookie身份验证（企业）：

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://testrail.yourcompany.com",
        "TESTRAIL_COOKIE_PATH": "~/path/to/sso/cookies.txt"
      }
    }
  }
}

克劳德代码（CLI）

添加 ~/.claude/settings.json 或者你的项目 .claude/settings.json:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

基罗

添加 .kiro/settings/mcp.json 在项目根目录中：

API密钥授权：

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

SSO Cookie身份验证（企业）：

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://testrail.yourcompany.com",
        "TESTRAIL_COOKIE_PATH": "~/path/to/sso/cookies.txt"
      }
    }
  }
}

光标

添加 .cursor/mcp.json 在项目根目录中：

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

帆板运动

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

本地开发

对于本地测试（未发布到npm），使用构建文件的绝对路径：

{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/testrail-mcp/build/src/index.js"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

环境变量

变量	必填	描述
`TESTRAIL_URL`	是	TestRail实例URL（例如。 `https://yourcompany.testrail.com`)
`TESTRAIL_EMAIL`	对于API密钥/密码验证	用户电子邮件地址
`TESTRAIL_API_KEY`	选项1	API键（来自TestRail中的“我的设置”）
`TESTRAIL_PASSWORD`	选项2	密码（如果API密钥不可用）
`TESTRAIL_COOKIE_PATH`	选项3	Netscape格式cookie文件的路径
`TESTRAIL_TOOLSETS`	否	逗号分隔的工具集名称或 `"all"` （默认：核心工具集）
`TESTRAIL_TOOLS`	否	要启用的其他单个工具名称
`TESTRAIL_DENIED_TOOLS_REGEX`	没有	正则表达式模式可以按名称排除工具
`TESTRAIL_PROJECT_IDS`	否	逗号分隔的项目ID用于限定服务器的范围（例如。 `"5"` 或 `"1,5,12"`)
`TESTRAIL_READ_ONLY_MODE`	否	设置为 `"true"` 仅公开读取操作

如果两者都有 TESTRAIL_API_KEY 和 TESTRAIL_PASSWORD 设置，则API键优先。

项目范围界定

使用 TESTRAIL_PROJECT_IDS 将服务器限制为特定项目。当您的TestRail实例有许多项目，但您只处理少数项目时，这很有用。

配置	描述提示	自动注入 `project_id`	限制
未设置	无	否	否
单一ID(`"5"`)	`[Project 5]` 附加到工具描述中	是--填补缺失 `project_id`	拒绝其他ID
多个ID(`"1,5,12"`)	`[Allowed projects: 1, 5, 12]` 附加	否--LLM必须选择	拒绝其他ID

# Scope to a single project (auto-injects project_id)
TESTRAIL_PROJECT_IDS="5"

# Scope to multiple projects (LLM must specify which)
TESTRAIL_PROJECT_IDS="1,5,12"

工具如 get_projects （无project_id输入）和 add_project （创建新）不受影响。实体范围的工具，如 get_case （采用case_id而非project_id）也不受影响。

工具集

工具分为18个工具集。 默认情况下启用9 （54种工具），以保持代币使用率低。使用 TESTRAIL_TOOLSETS 定制。

工具集	默认值	工具	说明
`projects`	是	5	CRUD项目
`suites`	是	5	套件CRUD
`sections`	是	6	CRUD+移动部分
`cases`	是	13	案例CRUD+批量+字段/类型
`runs`	是	6	运行CRUD+关闭
`tests`	是	2	在运行中读取测试
`results`	是	8	结果CRUD+批量+字段
`users`	是	5	用户查找+角色
`metadata`	是	4	优先级、状态、模板
`plans`	否	12	测试计划管理
`milestones`	否	5	里程碑CRUD
`groups`	否	5	组管理
`attachments`	无	8	文件附件
`configurations`	否	7	测试配置
`reports`	否	2	报告执行
`shared_steps`	否	5	共享步骤
`variables`	无	4	变量
`datasets`	否	5	数据集

工具集示例

# Only case and result management (21 tools)
TESTRAIL_TOOLSETS="cases,results"

# Everything (107 tools)
TESTRAIL_TOOLSETS="all"

# Default toolsets + specific additional tools
TESTRAIL_TOOLS="get_plan,get_plans,get_milestones"

# Block all destructive operations
TESTRAIL_DENIED_TOOLS_REGEX="^(delete_|close_)"

# Read-only mode (~40 tools)
TESTRAIL_READ_ONLY_MODE="true"

令牌效率

每个MCP工具定义都被注入到LLM上下文中 每一次谈话更多的工具=在模型甚至读取您的消息之前就燃烧了更多的令牌。该MCP旨在保持低成本。

默认配置使用约2000个令牌进行工具定义 --大约是公开所有107个工具所需成本的一半（约4000个令牌）。在10轮对话中，节省了约20000个代币。

配置	工具	~每回合令牌数
默认值（9个核心工具集）	54	~2000
只读模式	46	~1700
自定义（例如。 `cases,results`)	21	~800
所有工具集	107	~4000

如何

工具集过滤 --默认情况下，107个工具中只有54个暴露在外；非必要的工具集（计划、里程碑、组等）是可选择的
简洁的描述 --每个工具平均24个字符（5-10个单词），不是完整的句子
批量操作 — add_results, update_cases, delete_cases 接受数组，因此一次调用可以替换数十次往返（每次避免的往返都会保存完整的工具列表重新注入）
最大分页 --默认为每页250个项目（TestRail的最大值），所需调用更少
原始JSON响应 --没有元数据信封或包装器开销；删除/关闭操作仅返回 {"success": true}
分层过滤 — TESTRAIL_TOOLSETS → TESTRAIL_TOOLS → TESTRAIL_READ_ONLY_MODE → TESTRAIL_DENIED_TOOLS_REGEX 全部作曲，这样你就可以精确地调谐到你需要的东西

速率限制

对HTTP 429响应进行指数回退的自动重试。尊敬 Retry-After 头球最多重试3次。

可用工具（107）

Click to expand full tool list

项目（5）

get_project --按ID获取项目
get_projects --列出所有项目
add_project --创建新项目
update_project --更新现有项目
delete_project --按ID删除项目

套房（5）

get_suite --按ID获取测试套件
get_suites --列出项目的套件
add_suite --创建测试套件
update_suite --更新测试套件
delete_suite --删除测试套件

第（6）节

get_section --按ID获取分区
get_sections --列出项目/套件中的部分
add_section --创建一个分区
move_section --将部分移动到新父级
update_section --更新一个部分
delete_section --删除一个部分

案例（13）

get_case --按ID获取测试用例
get_cases --列出带有过滤器的测试用例
get_history_for_case --获取案例的变更历史记录
add_case --在部分中创建测试用例
update_case --更新测试用例
update_cases --批量更新多个测试用例
delete_case --删除测试用例
delete_cases --批量删除多个测试用例
copy_cases_to_section --将案例复制到另一个部分
move_cases_to_section --将案例移动到另一个部分
get_case_fields --列出可用案例字段
add_case_field --创建自定义案例字段
get_case_types --列出可用的案例类型

跑步（6）

get_run --按ID获取测试运行
get_runs --列出项目的测试运行
add_run --创建测试运行
update_run --更新测试运行
close_run --关闭试运行
delete_run --删除测试运行

测试（2）

get_test --按ID进行测试
get_tests --列出运行中的测试

结果（8）

get_results --获取测试结果
get_results_for_case --在运行中获取案例结果
get_results_for_run --获取跑步的所有结果
add_result --添加测试结果
add_result_for_case --在运行中为案例添加结果
add_results --批量添加跑步结果
add_results_for_cases --按案例批量添加跑步结果
get_result_fields --列出可用结果字段

平面图（12）

get_plan --按ID获取测试计划
get_plans --列出项目的测试计划
add_plan --制定测试计划
add_plan_entry --在计划中添加套房条目
add_run_to_plan_entry --在计划条目中添加跑步记录
update_plan --更新测试计划
update_plan_entry --更新计划条目
update_run_in_plan_entry --更新计划条目中的跑步记录
close_plan --关闭测试计划
delete_plan --删除测试计划
delete_plan_entry --删除计划条目
delete_run_from_plan_entry --从计划条目中删除跑步记录

里程碑（5）

get_milestone --按ID获取里程碑
get_milestones --列出项目的里程碑
add_milestone --创建里程碑
update_milestone --更新里程碑
delete_milestone --删除里程碑

用户和角色（5）

get_user --按ID获取用户
get_current_user --获取经过身份验证的用户
get_user_by_email --通过电子邮件查找用户
get_users --列出用户
get_roles --列出可用的用户角色

团体（5）

get_group --按ID获取组
get_groups --列出所有组
add_group --创建用户组
update_group --更新用户组
delete_group --删除用户组

附件（8）

add_attachment_to_plan --将文件附加到测试计划
add_attachment_to_result --将文件附加到结果
add_attachment_to_run --将文件附加到跑步记录中
add_attachment_to_case --将文件附加到案例中
get_attachments_for_case --列出案例的附件
get_attachments_for_run --列出跑步的附件
get_attachment --按ID获取附件元数据
delete_attachment --删除附件

配置（7）

get_configs --列出项目的配置
add_config_group --创建配置组
add_config --向组中添加配置
update_config_group --更新配置组
update_config --更新配置
delete_config_group --删除配置组
delete_config --删除配置

元数据（4）

get_priorities --列出可用优先级
get_statuses --列出可用的测试状态
get_case_statuses --列出可用的案例状态
get_templates --列出项目的模板

报告（2）

get_reports --列出项目的报告
run_report --执行报告模板

共享步骤（5）

get_shared_step --按ID获取共享步骤
get_shared_steps --列出项目的共享步骤
add_shared_step --创建共享步骤
update_shared_step --更新共享步骤
delete_shared_step --删除共享步骤

变量（4）

get_variables --列出项目的变量
add_variable --创建一个变量
update_variable --更新变量
delete_variable --删除变量

数据集（5）

get_dataset --按ID获取数据集
get_datasets --列出项目的数据集
add_dataset --创建数据集
update_dataset --更新数据集
delete_dataset --删除数据集

故障排除

“身份验证失败：用户/密码或会话cookie无效或丢失”

API密钥授权： 验证API密钥是否正确，并且API已在TestRail中启用（管理>站点设置>API）。
SSO Cookie身份验证： 您的SSO Cookie可能已过期。刷新它们（重新与SSO提供商进行身份验证），然后重试。服务器自动检测cookie文件更改。

“TESTRAIL_URL环境变量是必需的”

确保 TESTRAIL_URL 在MCP配置中设置 env 块。URL不应有尾随斜线。

SSO登录流程失败

确保您的SSO Cookie新鲜有效
在浏览器中打开您的TestRail URL进行测试——如果您可以访问它，Cookie应该可以工作
检查一下 TESTRAIL_COOKIE_PATH 指向正确的Netscape格式cookie文件
服务器登录到stderr——检查MCP客户端的日志以获取详细的SSO流输出

工具未出现

检查 TESTRAIL_TOOLSETS --默认情况下，只启用了9个核心工具集（54个工具）。使用 TESTRAIL_TOOLSETS="all" 所有107个工具。

许可证

麻省理工学院