TestRail MCP Server
Provides tools for interacting with TestRail's API, enabling management of test cases, projects, suites, sections, test runs, tests, results, test plans, milestones, and shared steps.
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 Show me the test cases in the Smoke test suite"
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.
TestRail MCP Server
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.
Available Tools
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
Requirements
Node.js 20.18.1 or newer
Git
A TestRail account with API access
Use with VS Code
Add the following to .vscode/mcp.json. npx downloads this repository, builds the package, and runs the MCP server locally. Each user supplies their own TestRail credentials.
{
"servers": {
"testrail": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"--package=git+https://github.com/akoehlerbbw/testrail-mcp.git#main",
"mcp-testrail"
],
"env": {
"TESTRAIL_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "${input:testrail_username}",
"TESTRAIL_API_KEY": "${input:testrail_api_key}"
}
}
},
"inputs": [
{
"id": "testrail_username",
"type": "promptString",
"description": "TestRail email address"
},
{
"id": "testrail_api_key",
"type": "promptString",
"description": "TestRail API key",
"password": true
}
]
}Start the server from the MCP view in VS Code. The first start can take longer while npx downloads dependencies and builds the package.
The #main reference follows the latest repository version. For repeatable installations, replace it with a release tag or commit SHA.
Other MCP clients
Clients that use the mcpServers configuration format can use the same command and environment variables:
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": [
"-y",
"--package=git+https://github.com/akoehlerbbw/testrail-mcp.git#main",
"mcp-testrail"
],
"env": {
"TESTRAIL_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "your-email@example.com",
"TESTRAIL_API_KEY": "your-api-key"
}
}
}
}Do not commit a configuration containing real credentials. Prefer your MCP client's secure input or secret-storage support.
Troubleshooting
spawn npx ENOENT/spawn node ENOENT(commonly on macOS): your MCP host (Cursor, Claude Code, Claude Desktop, …) cannot findnpxornodeat 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/),npxlives 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>.logClaude Code / Claude Desktop:
~/Library/Logs/Claude/
Fix by replacing
"npx"in your MCP config with its absolute path. Runwhich npxin 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": [ "-y", "--package=git+https://github.com/akoehlerbbw/testrail-mcp.git#main", "mcp-testrail" ], "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 — ifmcp-testrailis failing for this reason, your othernpx-launched servers are likely failing too.Authentication issues: Check your TestRail API credentials.
Your conversation is too long: Use
limitandoffsetparameters 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.mdorAGENTS.mdso 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 fields
Contributing
Contributions are welcome. Open an issue before submitting a pull request, keep changes focused, and include tests for behavioral changes. Pull requests must pass the test and build workflow and require maintainer review before merge.
Security vulnerabilities should be reported privately according to SECURITY.md, not through a public issue.
Acknowledgements
Available Tools
44 toolsaddBddA
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).
addCaseA
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: title (required), sectionId (required), refs, typeId, +9 more.
addMilestoneC
Creates a new milestone in a TestRail project / TestRailプロジェクトに新しいマイルストーンを作成します
Inputs: name (required), projectId (required), refs, dueOn, +3 more.
addPlanB
Creates a new test plan in a TestRail project / TestRailプロジェクトに新しいテストプランを作成します
Inputs: name (required), projectId (required), entries, description, +1 more.
addPlanEntryB
Adds a new test plan entry to an existing test plan / 既存のテストプランに新しいテストプランエントリーを追加します
Inputs: planId (required), suiteId (required), name, refs, +6 more.
addResultForCaseB
Adds a test result for a specific test case in a test run / テスト実行内の特定のテストケースにテスト結果を追加します
Inputs: runId (required), caseId (required), comment, defects, +4 more.
addResultsForCasesB
Adds test results for multiple test cases in a test run / テスト実行内の複数のテストケースにテスト結果を追加します
Inputs: runId (required), results (required).
addRunC
Creates a new test run in a TestRail project / TestRailプロジェクトに新しいテスト実行を作成します
Inputs: name (required), projectId (required), refs, caseIds, +6 more.
addRunToPlanEntryC
Adds a new test run to an existing plan entry / 既存のプランエントリーに新しいテストランを追加します
Inputs: planId (required), entryId (required), configIds (required), refs, +4 more.
addSectionB
Creates a new section in a TestRail project / TestRailプロジェクトに新しいセクションを作成します
Inputs: name (required), projectId (required), suiteId, parentId, +1 more.
addSuiteB
Creates a new test suite in the specified project / 指定されたプロジェクトに新しいテストスイートを作成します
Inputs: name (required), projectId (required), description.
copyToSectionA
Copies specified test cases to a target section while keeping the originals / 指定されたテストケースを対象のセクションにコピーし、元のケースは保持します
Inputs: caseIds (required), sectionId (required).
deleteCaseB
Deletes a test case from TestRail / TestRailからテストケースを削除します
Inputs: caseId (required).
deleteSectionB
Deletes a section / セクションを削除します
Inputs: sectionId (required), soft.
getBddB
Exports a BDD test case as a .feature file in Gherkin format. REQUIRED: caseId.
Inputs: caseId (required).
getCaseA
Retrieves complete details for a single test case including steps, expected results, and prerequisites. REQUIRED: caseId.
Inputs: caseId (required).
getCaseFieldsA
Retrieves all available test case fields in TestRail / TestRailで利用可能な全テストケースフィールドを取得します
Inputs: no named parameters.
getCaseHistoryA
Retrieves the change history of a test case including updates to fields and custom fields / テストケースの変更履歴(フィールドとカスタムフィールドの更新を含む)を取得します
Inputs: caseId (required).
getCasesA
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: suiteId (required), projectId (required), refs, limit, +10 more.
getCaseTypesA
Retrieves all available test case types in TestRail / TestRailで利用可能な全テストケースタイプを取得します
Inputs: no named parameters.
getMilestonesB
Retrieves all milestones for a specified TestRail project / 指定されたTestRailプロジェクトの全マイルストーンを取得します
Inputs: projectId (required).
getPlanA
Retrieves a TestRail test plan with all entries and child runs
Inputs: planId (required).
getPlansB
Retrieves all test plans for a specified TestRail project / 指定されたTestRailプロジェクトの全テストプランを取得します
Inputs: projectId (required).
getProjectB
Retrieves details of a specific TestRail project by ID / 特定のTestRailプロジェクトの詳細をIDで取得します
Inputs: projectId (required).
getProjectsA
Retrieves all TestRail projects / すべてのTestRailプロジェクトを取得します
Inputs: no named parameters.
getResultsC
Retrieves test results for a specific test / 特定のテストのテスト結果を取得します
Inputs: testId (required), limit, offset, statusId, +1 more.
getResultsForCaseC
Retrieves test results for a specific test case in a test run / テスト実行内の特定のテストケースのテスト結果を取得します
Inputs: runId (required), caseId (required), limit, offset, +2 more.
getResultsForRunB
Retrieves all test results for a test run / テスト実行の全テスト結果を取得します
Inputs: runId (required), limit, offset, statusId, +1 more.
getRunA
Retrieves details of a specific test run by ID / 特定のテスト実行の詳細をIDで取得します
Inputs: runId (required).
getRunsB
Retrieves all test runs for a specified TestRail project / 指定されたTestRailプロジェクトの全テスト実行を取得します
Inputs: projectId (required), limit, offset, suiteId, +4 more.
getSectionB
Retrieves details of a specific section by ID / 特定のセクションの詳細をIDで取得します
Inputs: sectionId (required).
getSectionsA
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), limit, offset, suiteId.
getSuiteB
Retrieves details of a specific test suite by ID / 特定のテストスイートの詳細をIDで取得します
Inputs: suiteId (required).
getSuitesA
Retrieves all test suites for a specified TestRail project / 指定されたTestRailプロジェクトの全テストスイートを取得します
Inputs: projectId (required).
getTestA
Retrieves complete details for a single test, including all fields such as status, type, and results / 単一のテストの完全な詳細(ステータス、タイプ、結果などのすべてのフィールドを含む)を取得します
Inputs: testId (required).
getTestsB
Retrieves a list of tests for a test run / テスト実行に含まれるテスト一覧を取得します
Inputs: runId (required), limit, offset.
moveSectionC
Moves a section to a new position in the test hierarchy / テスト階層内の新しい位置にセクションを移動します
Inputs: parentId (required), sectionId (required), afterId.
moveToSectionB
Moves specified test cases to a target section / 指定されたテストケースを対象のセクションに移動します
Inputs: caseIds (required), sectionId (required).
updateCaseA
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), refs, title, typeId, +9 more.
updateCasesA
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: caseIds (required), suiteId (required), projectId (required), refs, +11 more.
updateRunB
Updates an existing test run / 既存のテスト実行を更新します
Inputs: runId (required), name, refs, caseIds, +4 more.
updateSectionC
Updates an existing section / 既存のセクションを更新します
Inputs: sectionId (required), name, description.
updateSuiteB
Updates an existing test suite / 既存のテストスイートを更新します
Inputs: suiteId (required), name, description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 44 tools
Most tools target a distinct resource and action, and the singular/plural get patterns are clear. The main confusion risk is moveSection vs moveToSection, which sound similar but operate on different things, and the several result-fetching variants could be briefly confusing.
Tool names mostly follow a consistent verb+resource camelCase pattern such as getCases, addCase, updateCase, deleteSection, and addRun. Minor deviations like addBdd/getBdd and nested names like addRunToPlanEntry are understandable but slightly break the uniform pattern.
44 tools is a very large surface for an MCP server. While TestRail covers many entity types and most tools correspond to real API operations, the count makes selection harder and exceeds the range where a tool set feels tight and easily navigable.
Core case, section, run, and result workflows are well covered, including bulk operations and BDD import/export. However, several secondary resources are incomplete: milestones only support get/add, shared steps are read-only, and plans lack update/delete operations.
Maintenance
Related MCP Connectors
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Manage Orangescrum projects, tasks, users, sprints, test cases, releases, and risks from AI tools.
Test management for AI agents: cases, runs, results, cycles and traceability.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables management of TestRail projects, test cases, runs, and results directly through MCP-supported clients. It provides a comprehensive set of tools to interact with the TestRail API for seamless test cycle management within AI environments.426,221 npm42MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for TestRail that enables AI assistants to interact with TestRail's test management platform. It can query and manage projects, test cases, runs, results, plans, milestones, and more.MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with TestRail test management system, supporting full CRUD operations on projects, suites, sections, test cases, runs, results, plans, and milestones.35327 npm1MIT
- AlicenseBqualityDmaintenanceEnables TestRail test management through MCP tools, allowing users to manage projects, test cases, runs, and results via natural language.2531 npmMIT