TestRail

You can run a TestRail MCP Server locally to manage test data directly from your conversations with Claude AI or other MCP-enabled clients. This server exposes a wide set of actions for projects, suites, cases, sections, runs, tests, results, plans, milestones, and shared steps, enabling you to work with TestRail without leaving your chat or IDE.

How to use

Connect your MCP client to the TestRail MCP Server by configuring a local runtime that executes the MCP package and exposes the tools listed below. Once connected, you can retrieve and modify test data across projects, suites, cases, sections, and runs, then view results and history all from within your messaging client.

How to install

Prerequisites you need before starting:

• Node.js installed on your machine (version 14+ recommended)
• npm or yarn installed to manage packages

Install and run the MCP server using the provided runtime command snippet. Create a configuration that points to your TestRail instance and credentials.

{
  "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
      }
    }
  }
}

Configuration and start

Place the configuration in your MCP client according to the structure shown above. Start the MCP server using your client’s standard run procedure. Once running, your client can invoke all available TestRail tools from within your conversations.

Security and credentials

Protect your TestRail credentials. Store the API key and username securely and avoid committing them to version-controlled files. Use environment variables as shown in the example to keep secrets out of your code.

Troubleshooting

If you encounter issues, check these common areas:

• Spawn or startup errors: confirm Node.js is installed and accessible in your PATH.
• Connection issues: ensure the MCP server is running and the provided TestRail URL and credentials are correct.
• Authentication errors: verify your API credentials in the environment variables.
• SSE or network errors: verify the server port is open and reachable from your client.

Notes

This MCP server exposes a comprehensive set of TestRail capabilities, including fetching and updating projects, suites, cases, sections, runs, tests, results, plans, milestones, and shared steps. Use these tools to automate actions and pull data into your conversations.

Available tools

getProjects

Retrieve a list of all projects in TestRail.

getProject

Fetch details for a single project by ID.

getSuites

Get all suites within a project.

getSuite

Fetch a single suite by ID.

addSuite

Create a new suite in a project.

updateSuite

Update an existing suite.

getCase

Retrieve a single test case by ID.

getCases

Retrieve multiple test cases within a project or suite.

addCase

Create a new test case.

updateCase

Update an existing test case.

deleteCase

Delete a test case.

getCaseTypes

List available test case types.

getCaseFields

List custom fields for cases.

copyToSection

Copy a case to another section.

moveToSection

Move a case to a different section.

getCaseHistory

Retrieve historical changes for a case.

updateCases

Update multiple cases in a batch.

getSection

Fetch a single section by ID.

getSections

List sections in a project or suite.

addSection

Create a new section.

moveSection

Move a section to a different folder or position.

updateSection

Update an existing section.

deleteSection

Delete a section.

getRuns

Retrieve test runs for a project.

getRun

Fetch a single run by ID.

addRun

Create a new test run.

updateRun

Update an existing test run.

getTests

List tests within a run or project.

getTest

Fetch a single test by ID.

getResults

Retrieve test results for a run or case.

getResultsForCase

Get results for a specific case.

getResultsForRun

Get results for a specific run.

addResultForCase

Add a result for a single case.

addResultsForCases

Add results for multiple cases at once.

getPlans

List test plans.

getMilestones

List milestones.

getSharedSteps

Retrieve shared steps available for reuse.