TestRail MCP Server

A Model Context Protocol (MCP) server that provides TestRail integration tools for AI assistants like Cursor.

Features

Get TestRail test cases, projects, suites, runs, and tests
Update test cases, runs, and tests
Add test results and attachments
Full TestRail API integration
Seamless integration with Cursor and other MCP-compatible AI assistants

Quick Start

Prerequisites

Node.js 18.17.0 or higher
npm

Installation Options

Option 1: Using npm package (Recommended)

# Install globally
npm install -g testrail-mcp-server

# Or install locally
npm install testrail-mcp-server

Option 2: From source

# Clone and setup
git clone https://github.com/Derrbal/testrail-mcp.git
cd testrail-mcp
npm install
npm run build

Configure Environment Variables

Create a .env file in your project root or set environment variables:

TESTRAIL_USERNAME=your_testrail_username
TESTRAIL_API_KEY=your_testrail_api_key
TESTRAIL_URL=https://your-instance.testrail.com

Cursor Integration

Setup

Option 1: Using npm package (Recommended)

Configure Cursor MCP Settings: Open Cursor and go to Settings → Extensions → MCP. Add the following configuration:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["testrail-mcp-server"],
      "env": {
        "TESTRAIL_USERNAME": "your_testrail_username",
        "TESTRAIL_API_KEY": "your_testrail_api_key",
        "TESTRAIL_URL": "https://your-instance.testrail.com"
      }
    }
  }
}

Option 2: Using local installation

Configure Cursor MCP Settings: Open Cursor and go to Settings → Extensions → MCP. Add the following configuration:

{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/path/to/testrail-mcp/dist/server.js"],
      "env": {
        "TESTRAIL_USERNAME": "your_testrail_username",
        "TESTRAIL_API_KEY": "your_testrail_api_key",
        "TESTRAIL_URL": "https://your-instance.testrail.com"
      }
    }
  }
}

Restart Cursor to load the MCP server configuration.

Usage

Using with Cursor

Once configured, you can use TestRail tools directly in Cursor's chat:

Using the npm package directly

You can also use the MCP server directly from the command line:

# Run the server (stdio transport)
npx testrail-mcp-server

# Or run with HTTP transport
npx testrail-mcp-server --http

Example Commands:

"Get all TestRail projects"
"Show me test cases for project ID 1"
"Update test case 123 with new title"
"Add a test result for test ID 456"
"Upload an attachment to test case 789"

Available Tools:

get_case - Fetch a TestRail test case by ID
add_case - Create a new test case in a section
update_case - Update a TestRail test case
get_projects - List all TestRail projects
get_project - Get project details
get_suites - Get test suites for a project
get_suite - Get suite details
get_cases - Get test cases with filtering
add_attachment_to_case - Upload file attachment
get_sections - Get test sections
get_runs - Get test runs
get_run - Get run details
update_run - Update test run
get_tests - Get tests in a run
get_test - Get test details
update_test - Update test
add_result - Add test result
get_case_fields - Get available custom fields for test cases

Troubleshooting

Common Issues:

Server not found: Ensure the path to dist/server.js is correct
Authentication errors: Verify your TestRail credentials in the environment variables
Permission denied: Make sure the server file is executable
Connection timeout: Check your TestRail URL and network connectivity

Debug Mode: Enable debug logging by adding to your environment variables:

DEBUG=true
LOG_LEVEL=debug

Deployment Options

Local Development

# Run in development mode
npm run dev

# Start the server (stdio transport)
npm start

# Start the server (HTTP transport on port 1823)
npm run start:http

# Run tests
npm test

Docker Deployment

Quick Start:

# Set environment variables
export TESTRAIL_USERNAME="your_testrail_username"
export TESTRAIL_API_KEY="your_testrail_api_key"
export TESTRAIL_URL="https://your-instance.testrail.com"

# Build and run with Docker Compose
docker-compose up -d

Manual Build:

# Build the image
docker build -t testrail-mcp-server .

# Run the container
docker run -d \
  --name testrail-mcp-server \
  -p 1823:1823 \
  -e TESTRAIL_USERNAME=your_username \
  -e TESTRAIL_API_KEY=your_api_key \
  -e TESTRAIL_URL=https://your-instance.testrail.com \
  testrail-mcp-server

Security Considerations

Store TestRail API keys securely using environment variables
Never commit API keys to version control
Use HTTPS for TestRail URLs
Consider using Docker secrets for production deployments
Regularly rotate API keys

License

MIT

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with TestRail test management systems through comprehensive API integration. Supports retrieving and updating test cases, projects, suites, runs, and results, plus adding attachments and managing test data through natural language commands.

Related MCP Servers

Web-QA
GroundNG
-
security
A
license
-
quality
AI-powered agent that streamlines web testing workflows by allowing developers to record, execute, and discover tests using natural language prompts in their AI coding assistants.
Last updated -
57
Apache 2.0
Statsig MCP Server
GeLi2001
-
security
A
license
-
quality
Enables AI assistants to interact with Statsig's feature management and experimentation platform, allowing them to check feature flags, retrieve configurations, get experiment assignments, and log events.
Last updated -
MIT License
GitLab MCP Server
amirsina-mandegari
-
security
F
license
-
quality
Connects AI assistants to GitLab, allowing users to manage merge requests, view reviews, and interact with discussions through natural language queries.
Last updated -
8
TestRail MCP Server
moneyforward
-
security
F
license
-
quality
A Model Context Protocol server that provides integration with TestRail, allowing AI assistants to interact with TestRail projects, test cases, test runs, and results.
Last updated -
1

View all related MCP servers

TestRail MCP Server