The TestRail MCP Server enables comprehensive management of TestRail entities directly from AI clients, covering the full test lifecycle:
Projects
List all projects and retrieve specific project details.
Test Suites
List, retrieve, create, and update test suites.
Test Cases
Full CRUD operations (get, list with filtering/pagination, create, update, delete)
Bulk update multiple cases simultaneously
Copy or move cases between sections
View case change history
Get available case types and fields
Import BDD/Gherkin .feature files and export test cases as .feature files
Sections
Retrieve, create, move, update, and delete sections (with soft delete support), with pagination.
Test Runs
List, retrieve, create, and update test runs.
Tests
List tests in a run (with pagination) and retrieve full test details.
Test Results
Retrieve results by test, case within a run, or entire run
Add results for individual or multiple test cases at once
Test Plans
List all plans, create new plans, add entries to plans, and add runs to plan entries.
Milestones
List all milestones for a project.
Shared Steps
List all shared steps for a project with filtering and pagination.
Provides comprehensive tools for managing TestRail resources, including test cases, projects, suites, runs, sections, tests, results, plans, and milestones.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TestRail MCP Server list the test cases for project 1"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This Model Context Protocol (MCP) server provides tools for interacting with TestRail directly from Claude AI and other MCP-supported clients like Cursor. It allows you to manage test cases, projects, suites, runs, and more without leaving your conversation with the AI.
The TestRail MCP server provides the following tools:
Category | Tools |
Projects |
|
Suites |
|
Cases |
|
Sections |
|
Runs |
|
Tests |
|
Results |
|
Plans |
|
Milestones |
|
Shared Steps |
|
Related MCP server: TestRail MCP Server
You can connect this MCP server by setting like the below. This method uses npx to automatically download and run the latest version of the package, eliminating the need for local installation.
// 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 (commonly on macOS): your MCP host (Cursor, Claude Code, Claude Desktop, …) cannot find npx or node at process-spawn time. The chat UI usually surfaces this as a generic "MCP server doesn't work" with no useful detail; the per-server log is the diagnostic source of truth.
Why it happens on macOS: GUI apps launched from the Dock, Spotlight, or Finder inherit launchd's minimal PATH (/usr/bin:/bin:/usr/sbin:/sbin). If you installed Node via a version manager (nvm, asdf, mise, fnm, Volta) or Apple Silicon Homebrew (/opt/homebrew/bin/), npx lives outside that PATH — only your shell startup file (~/.zshrc / ~/.bashrc) adds it. Your terminal works because the shell ran the startup file; the GUI-app process never did.
Diagnose by checking the per-server log for spawn npx ENOENT:
Cursor: ~/Library/Application Support/Cursor/logs/<session>/window<N>/exthost/anysphere.cursor-mcp/MCP <server>.log
Claude Code / Claude Desktop: ~/Library/Logs/Claude/
Fix by replacing "npx" in your MCP config with its absolute path. Run which npx in your normal terminal:
/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 NodeThen update your MCP config:
{
"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"
}
}
}
}Restart your MCP client after the change. The same fix applies to every npx-launched MCP server — if mcp-testrail is failing for this reason, your other npx-launched servers are likely failing too.
Authentication issues: Check your TestRail API credentials.
Your conversation is too long: Use limit and offset parameters for test cases and sections to paginate results.
HTTP 400 errors when creating/updating test cases: TestRail projects have different templates, custom fields, and required fields. This MCP server passes your parameters directly to the TestRail API — it does not validate or transform them. If you encounter 400 errors, define your project's rules in CLAUDE.md or AGENTS.md so the LLM sends the correct parameters. For example:
# 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 fieldsContributions are welcome! Please feel free to submit a Pull Request.
Imports/uploads a .feature file (Gherkin BDD scenario) into a TestRail section. Creates a new test case with BDD template (template_id=4) and populates the custom_testrail_bdd_scenario field. REQUIRED: sectionId, featureContent (raw Gherkin text including Feature:, Scenario:, Given/When/Then).
Inputs: sectionId (required), featureContent (required).
Creates a new test case in TestRail. REQUIRED: sectionId, title. OPTIONAL: typeId, priorityId, templateId, customSteps, customExpected, customStepsSeparated, customFields, etc. Use getCaseTypes to find valid typeId values. NOTE: templateId=2 is required to use customStepsSeparated (array of step objects with 'content' and 'expected' fields). For simple text steps, use customSteps and customExpected instead. Use customFields for any additional custom fields (e.g., {custom_case_security_score: 'high'}).
Inputs: sectionId (required), title (required), typeId, priorityId, +9 more.
Creates a new test plan in a TestRail project / TestRailプロジェクトに新しいテストプランを作成します
Inputs: projectId (required), name (required), description, milestoneId, +1 more.
Adds a new test plan entry to an existing test plan / 既存のテストプランに新しいテストプランエントリーを追加します
Inputs: planId (required), suiteId (required), name, description, +6 more.
Adds a test result for a specific test case in a test run / テスト実行内の特定のテストケースにテスト結果を追加します
Inputs: runId (required), caseId (required), statusId, comment, +4 more.
Adds test results for multiple test cases in a test run / テスト実行内の複数のテストケースにテスト結果を追加します
Inputs: runId (required), results (required).
Creates a new test run in a TestRail project / TestRailプロジェクトに新しいテスト実行を作成します
Inputs: projectId (required), name (required), suiteId, description, +6 more.
Adds a new test run to an existing plan entry / 既存のプランエントリーに新しいテストランを追加します
Inputs: planId (required), entryId (required), configIds (required), description, +4 more.
Creates a new section in a TestRail project / TestRailプロジェクトに新しいセクションを作成します
Inputs: projectId (required), name (required), description, parentId, +1 more.
Creates a new test suite in the specified project / 指定されたプロジェクトに新しいテストスイートを作成します
Inputs: projectId (required), name (required), description.
Copies specified test cases to a target section while keeping the originals / 指定されたテストケースを対象のセクションにコピーし、元のケースは保持します
Inputs: caseIds (required), sectionId (required).
Deletes a test case from TestRail / TestRailからテストケースを削除します
Inputs: caseId (required).
Deletes a section / セクションを削除します
Inputs: sectionId (required), soft.
Exports a BDD test case as a .feature file in Gherkin format. REQUIRED: caseId.
Inputs: caseId (required).
Retrieves complete details for a single test case including steps, expected results, and prerequisites. REQUIRED: caseId.
Inputs: caseId (required).
Retrieves all available test case fields in TestRail / TestRailで利用可能な全テストケースフィールドを取得します
Inputs: no named parameters.
Retrieves the change history of a test case including updates to fields and custom fields / テストケースの変更履歴（フィールドとカスタムフィールドの更新を含む）を取得します
Inputs: caseId (required).
Retrieves test cases list with basic fields only (excludes steps/expected results for performance). REQUIRED: projectId, suiteId. OPTIONAL: createdBy, filter, limit (default 50), milestoneId, offset (default 0), priorityId, refs, sectionId, templateId, typeId, updatedBy, labelId. Use getCase for full details.
Inputs: projectId (required), suiteId (required), createdBy, filter, +10 more.
Retrieves all available test case types in TestRail / TestRailで利用可能な全テストケースタイプを取得します
Inputs: no named parameters.
Retrieves all milestones for a specified TestRail project / 指定されたTestRailプロジェクトの全マイルストーンを取得します
Inputs: projectId (required).
Retrieves all test plans for a specified TestRail project / 指定されたTestRailプロジェクトの全テストプランを取得します
Inputs: projectId (required).
Retrieves details of a specific TestRail project by ID / 特定のTestRailプロジェクトの詳細をIDで取得します
Inputs: projectId (required).
Retrieves all TestRail projects / すべてのTestRailプロジェクトを取得します
Inputs: no named parameters.
Retrieves test results for a specific test / 特定のテストのテスト結果を取得します
Inputs: testId (required), limit, offset, statusId, +1 more.
Retrieves test results for a specific test case in a test run / テスト実行内の特定のテストケースのテスト結果を取得します
Inputs: runId (required), caseId (required), limit, offset, +2 more.
Retrieves all test results for a test run / テスト実行の全テスト結果を取得します
Inputs: runId (required), limit, offset, statusId, +1 more.
Retrieves details of a specific test run by ID / 特定のテスト実行の詳細をIDで取得します
Inputs: runId (required).
Retrieves all test runs for a specified TestRail project / 指定されたTestRailプロジェクトの全テスト実行を取得します
Inputs: projectId (required), createdAfter, createdBefore, createdBy, +4 more.
Retrieves details of a specific section by ID / 特定のセクションの詳細をIDで取得します
Inputs: sectionId (required).
Retrieves sections for a specified project and suite. Supports pagination via limit and offset parameters (default: limit=250, offset=0). Use _links.next to determine if more pages are available. / 指定されたプロジェクトとスイートのセクションを取得します。limitとoffsetパラメータでページネーションをサポートします。
Inputs: projectId (required), suiteId, limit, offset.
Retrieves details of a specific test suite by ID / 特定のテストスイートの詳細をIDで取得します
Inputs: suiteId (required).
Retrieves all test suites for a specified TestRail project / 指定されたTestRailプロジェクトの全テストスイートを取得します
Inputs: projectId (required).
Retrieves complete details for a single test, including all fields such as status, type, and results / 単一のテストの完全な詳細（ステータス、タイプ、結果などのすべてのフィールドを含む）を取得します
Inputs: testId (required).
Retrieves a list of tests for a test run / テスト実行に含まれるテスト一覧を取得します
Inputs: runId (required), limit, offset.
Moves a section to a new position in the test hierarchy / テスト階層内の新しい位置にセクションを移動します
Inputs: sectionId (required), parentId (required), afterId.
Moves specified test cases to a target section / 指定されたテストケースを対象のセクションに移動します
Inputs: caseIds (required), sectionId (required).
Updates an existing test case. REQUIRED: caseId. OPTIONAL: title, typeId, priorityId, templateId, customSteps, customExpected, customStepsSeparated, customFields, etc. Only specified fields will be updated. NOTE: templateId=2 is required to use customStepsSeparated (array of step objects with 'content' and 'expected' fields). For simple text steps, use customSteps and customExpected instead. Use customFields for any additional custom fields (e.g., {custom_case_security_score: 'high'}).
Inputs: caseId (required), title, typeId, priorityId, +9 more.
Updates multiple test cases simultaneously with the same field values / 複数のテストケースを同じフィールド値で一括更新します. NOTE: templateId=2 is required to use customStepsSeparated (array of step objects with 'content' and 'expected' fields). For simple text steps, use customSteps and customExpected instead. Use customFields for any additional custom fields (e.g., {custom_case_security_score: 'high'}).
Inputs: projectId (required), suiteId (required), caseIds (required), title, +11 more.
Updates an existing test run / 既存のテスト実行を更新します
Inputs: runId (required), name, description, milestoneId, +4 more.
Updates an existing section / 既存のセクションを更新します
Inputs: sectionId (required), name, description.
Updates an existing test suite / 既存のテストスイートを更新します
Inputs: suiteId (required), name, description.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 42 tools
Each tool targets a distinct entity or operation, with clear differentiation between similar tools (e.g., copyToSection vs moveToSection, getResultsForCase vs getResultsForRun). Descriptions explicitly state required and optional parameters, reducing ambiguity.
All tool names follow a consistent camelCase verb_noun pattern (e.g., addCase, getCases, deleteSection). Even compound operations like copyToSection and moveToSection follow a predictable structure. No mixing of conventions.
42 tools is on the higher end but appropriate for a comprehensive TestRail API wrapper covering CRUD for cases, sections, suites, runs, plans, results, and metadata. The count could be slightly trimmed (e.g., merging some getters), but it remains manageable for the domain.
The tool surface covers most core CRUD operations for projects, suites, sections, cases, runs, and plans. However, notable gaps exist: missing delete for suites, plans, and runs, and no update for plans. Also absent are tools for milestones (get only), users, and attachments.
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Test management for AI agents: cases, runs, results, cycles and traceability.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Free test management over MCP: projects, test cases, plans, runs, environments and tasks.
