# @bun913/mcp-testrail 中文文档 规范地址：https://npmcn.com/package/%40bun913/mcp-testrail/ 版本：0\.19\.9 npm 元数据更新时间：2026-06-08T23:16:41.202Z 中文译文更新时间：2026-11-08T19:41:28.735Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bun913/mcp-testrail 原文对照：https://npmcn.com/package/%40bun913/mcp-testrail/?lang=original 项目主页：https://github.com/bun913/mcp-testrail 源码仓库：https://github.com/bun913/mcp-testrail ## 关键信息（来自 npm 元数据） - 包体积（解压后）：403 kB，120 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.18\.1 - 运行依赖：6 个 - 首次发布：2025-04-22T13:08:10.057Z - 最新版本发布：2026-06-08T23:16:40.930Z - 近 30 天下载量：17958（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：33（近 12 个月 15 个） ## 中文简介 [![](https://flatt.tech/assets/images/badges/gmo-oss.svg)](https://flatt.tech/oss/gmo/trampoline) ## 安装 ```sh npm install @bun913/mcp-testrail ``` 也可以使用：`pnpm add @bun913/mcp-testrail`、`yarn add @bun913/mcp-testrail`、`bun add @bun913/mcp-testrail` ## README # TestRail MCP 服务器 [![](https://flatt.tech/assets/images/badges/gmo-oss.svg)](https://flatt.tech/oss/gmo/trampoline) 这个模式上下文协议(MCP)服务器提供了直接从克洛德AI和Cursor等MCP支持的其他客户端与TestRail互动的工具. 它允许你管理测试案例,项目,套房,运行,以及更多不离开你与AI的对话. ## 可用工具 TestRail MCP 服务器提供了以下工具: | 类别 | 工具 | | --- | --- | | **项目** | `getProjects`, (中文(简体) ), `getProject` | | **诉讼** | `getSuites`, (中文(简体) ), `getSuite`, (中文(简体) ), `addSuite`, (中文(简体) ), `updateSuite` | | **案例** | `getCase`, (中文(简体) ), `getCases`, (中文(简体) ), `addCase`, (中文(简体) ), `updateCase`, (中文(简体) ), `deleteCase`, (中文(简体) ), `getCaseTypes`, (中文(简体) ), `getCaseFields`, (中文(简体) ), `copyToSection`, (中文(简体) ), `moveToSection`, (中文(简体) ), `getCaseHistory`, (中文(简体) ), `updateCases`, (中文(简体) ), `addBdd`, (中文(简体) ), `getBdd` | | **节** | `getSection`, (中文(简体) ), `getSections`, (中文(简体) ), `addSection`, (中文(简体) ), `moveSection`, (中文(简体) ), `updateSection`, (中文(简体) ), `deleteSection` | | **运行** | `getRuns`, (中文(简体) ), `getRun`, (中文(简体) ), `addRun`, (中文(简体) ), `updateRun` | | **测试** | `getTests`, (中文(简体) ), `getTest` | | **结果** | `getResults`, (中文(简体) ), `getResultsForCase`, (中文(简体) ), `getResultsForRun`, (中文(简体) ), `addResultForCase`, (中文(简体) ), `addResultsForCases` | | **计划** | `getPlans` | | **里程碑** | `getMilestones` | | **共同步骤** | `getSharedSteps` | ## 使用量 您可以通过如下设置连接 MCP 服务器 。 这种方法使用 `npx` 以自动下载和运行软件包的最新版本,从而无需本地安装. ```json // Example configuration using npx { "mcpServers": { "testrail": { "command": "npx", "args": ["@bun913/mcp-testrail@latest"], "env": { "TESTRAIL_URL": "https://your-instance.testrail.io", // Replace with your TestRail URL "TESTRAIL_USERNAME": "your-email@example.com", // Replace with your TestRail username "TESTRAIL_API_KEY": "YOUR_API_KEY" // Replace with your TestRail API key } } } } ``` ## 解决问题 - **`spawn npx ENOENT` 编号 : `spawn node ENOENT` (常见于macOS)**: 您的 MCP 主机( Cursor, Claude Code, Claude Desktop,...) 找不到 `npx` 或者说 `node` 在过程发作时。 聊天UI通常将它表面显示为通用"MCP服务器不起作用",没有有用的细节;每个服务器日志是真实性的诊断源. **为什么它发生在macOS上:** 从 Dock 、 Spotlight 或 Finder 启动的 GUI 应用程序继承了启动的最小值 `PATH` (单位:千美元)`/usr/bin:/bin:/usr/sbin:/sbin`) (中文(简体) ). 如果您通过版本管理器安装了节点( N)`nvm`, (中文(简体) ), `asdf`, (中文(简体) ), `mise`, (中文(简体) ), `fnm`, (中文(简体) ), `Volta`或 Apple 硅母舰(`/opt/homebrew/bin/`, (中文(简体) ), `npx` 住在 PATH 之外, 只有您的外壳启动文件( Name`~/.zshrc` 编号 : `~/.bashrc`)加而为. 您的终端工作是因为 shell 运行了启动文件; GUI- app 进程从未运行过 . **诊断** 检查每个服务器日志 `spawn npx ENOENT`数字 : - **光标 :** `~/Library/Application Support/Cursor/logs//window/exthost/anysphere.cursor-mcp/MCP .log` - **克洛德代码/克洛德桌面 :** `~/Library/Logs/Claude/` **修补** 替换 `"npx"` 您的 MCP 配置的绝对路径。 运行 `which npx` 在正常终端中: ```text /Users/you/.nvm/versions/node/v24.15.0/bin/npx # nvm /opt/homebrew/bin/npx # Apple Silicon Homebrew /usr/local/bin/npx # Intel Homebrew / system Node ``` 然后更新您的 MCP 配置 : ```json { "mcpServers": { "testrail": { "command": "/Users/you/.nvm/versions/node/v24.15.0/bin/npx", "args": ["@bun913/mcp-testrail@latest"], "env": { "TESTRAIL_URL": "https://your-instance.testrail.io", "TESTRAIL_USERNAME": "your-email@example.com", "TESTRAIL_API_KEY": "YOUR_API_KEY" } } } } ``` 更改后重新启动您的 MCP 客户端 。 同样的固定适用于每个 `npx`\- 发射MCP服务器——如果 `mcp-testrail` 是因为这个原因,你另一个 `npx`\- 发射服务器也有可能失灵. - **认证问题**:检查您的 TestRail API 证书 . - **你的谈话太长了**: 使用 `limit` 财务报告和审定财务报表 `offset` 用于测试的参数和用于标出结果的分节. - **HTTP 400 创建/更新测试时出错**: TestRail 项目有不同的模板,自定义字段,以及需要的字段. 这个 MCP 服务器将您的参数直接传递给 TestRail API —— 它不会验证或转换它们. 如果遇到400个错误,请在 `CLAUDE.md` 或者说 `AGENTS.md` 所以LLM发送正确的参数. 例如: ```markdown # TestRail Rules for This Project - Project ID: 1 - Always use template 2 (Separated Steps) when creating test cases - Use `customStepsSeparated` (array of step objects) - Do NOT send `customSteps` or `customExpected` with template 2 - Required custom fields: custom_automation_type (default: 0) - Call `getCaseFields` at the start of a session to check available fields ``` ## 捐款 欢迎捐款! 请随意提交拉力请求. ## 鸣谢 - [测试Rail API](https://docs.testrail.techmatrix.jp/testrail/docs/702/api/) - [示范背景协议SDK](https://github.com/modelcontextprotocol/typescript-sdk) ## 常见问题 ### 如何安装 @bun913/mcp-testrail？ 在项目目录运行 npm install @bun913/mcp-testrail，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-testrail，可以用 npx mcp-testrail 直接运行。 ### @bun913/mcp-testrail 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @bun913/mcp-testrail 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bun913/mcp-testrail 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.18\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @bun913/mcp-testrail 可以商用吗？ @bun913/mcp-testrail 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @bun913/mcp-testrail 的下载量有多少？ 根据 npm 官方下载统计，@bun913/mcp-testrail 在 2026/10/09 – 2026/11/07 这 30 天内被下载 17,958 次，日均约 599 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bun913/mcp-testrail 还在维护吗？ 最新版本 0\.19\.9 发布于 2026/06/09（4 个月前）；至今共发布 33 个版本，其中过去 12 个月发布了 15 个；首次发布于 2025/04/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。