内容
# TestRail MCP 服务器
一个用于 TestRail 的模型上下文协议（MCP）服务器，允许通过标准化的协议与 TestRail 的核心实体进行交互。
## 功能特点
- **完整的 CRUD 支持**：对所有 TestRail 核心实体提供全面的创建、读取、更新和删除操作。
- **访问 TestRail 实体**：
- 项目、测试套件、章节、测试用例
- 测试运行、测试计划、里程碑
- 测试、测试结果、测试状态
- 数据集、标签、模板、优先级
- 用户、用户组、共享步骤
- 配置和配置组
- 附件
- **智能过滤**：增强的 `get_tests` 功能，支持内部 `section_id` 过滤（测试与章节测试用例的交叉引用）。
- **状态助手**：使用 `get_status_id_by_name` 立即解析数字状态 ID。
- **v6.2+ 增强支持**：支持运行和计划中的 `refs`，以及重大更改验证。
- **完整的 MCP 支持**：用于任何 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）的标准化协议。
## 🚀 快速开始（托管）
使用 TestRail MCP 的最快方式是通过我们在 `https://horizon.prefect.io/` 提供的托管实例。
使用以下命令将其添加到您喜欢的 AI 工具中：
### Codex CLI
```bash
codex mcp add --url https://kyzu-testrail.fastmcp.app/mcp kyzu-testrail
```
### Claude CLI
```bash
claude mcp add --scope local --transport http kyzu-testrail https://kyzu-testrail.fastmcp.app/mcp
```
### Gemini CLI
```bash
gemini mcp add kyzu-testrail https://kyzu-testrail.fastmcp.app/mcp --transport http
```
---
## 🛠️ 本地设置（自托管）
如果您更喜欢在本地运行服务器用于开发或私人使用。
### 1. 先决条件
- 在您的系统上安装 [uv](https://github.com/astral-sh/uv)。
- TestRail API 凭证（URL、用户名、API 密钥）。
### 2. 安装
```bash
git clone https://github.com/yourusername/testrail-mcp.git
cd testrail-mcp
uv sync
```
### 3. 配置
在根目录中创建 `.env` 文件：
```env
TESTRAIL_URL=https://your-instance.testrail.io
TESTRAIL_USERNAME=your-email@example.com
TESTRAIL_API_KEY=your-api-key
```
验证您的配置：
```bash
uv run testrail-mcp --config
```
### 4. 运行服务器
```bash
uv run testrail-mcp
```
### 5. 与 MCP 客户端（本地）一起使用
#### Codex CLI
```bash
codex mcp add testrail_mcp \
--env TESTRAIL_URL=<TESTRAIL_URL> \
--env TESTRAIL_USERNAME=<TESTRAIL_USERNAME> \
--env TESTRAIL_API_KEY=<TESTRAIL_API_KEY> \
-- uv --directory <REPO_PATH> run testrail-mcp
```
#### Claude Desktop
```json
{
"mcpServers": {
"testrail": {
"command": "uv",
"args": ["--directory", "<REPO_PATH>", "run", "testrail-mcp"],
"env": {
"TESTRAIL_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "your-email@example.com",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}
```
#### Cursor / Windsurf
```json
{
"name": "TestRail MCP",
"command": "uv",
"args": ["--directory", "<REPO_PATH>", "run", "testrail-mcp"],
"env": {
"TESTRAIL_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "your-email@example.com",
"TESTRAIL_API_KEY": "your-api-key"
}
}
```
#### Gemini CLI
```bash
gemini mcp add testrail \
--env TESTRAIL_URL=<TESTRAIL_URL> \
--env TESTRAIL_USERNAME=<TESTRAIL_USERNAME> \
--env TESTRAIL_API_KEY=<TESTRAIL_API_KEY> \
-- uv --directory <REPO_PATH> run testrail-mcp
```
## 开发
该服务器使用以下工具构建：
- [FastMCP](https://github.com/jlowin/fastmcp) - 用于构建 MCP 服务器的 Python 框架
- [Requests](https://requests.readthedocs.io/) - 用于 HTTP 通信
- [python-dotenv](https://github.com/theskumar/python-dotenv) - 用于环境管理
