TestRail MCP Server

TestRail MCP Server

What is this?

This tool connects your TestRail test management system with AI assistants like Cursor or Claude Desktop. It allows your AI assistant to read and update test cases, add test results, and manage your testing workflow through simple conversations.

Features

• View Test Cases: Show test cases, projects, and test runs
• Update Tests: Modify test case details, titles, and descriptions
• Add Results: Record test results and upload screenshots
• Search & Filter: Find specific tests or projects quickly
• File Attachments: Upload documents and images to test cases
• Full Integration: Works with Cursor, Claude Desktop, and other AI tools

Who is this for?

• QA Engineers who want to manage tests through AI conversations
• Project Managers who need quick access to test information
• Developers who want to integrate testing into their AI-assisted workflow
• Anyone who uses TestRail and wants to make it more accessible through AI

Quick Start

1. Install Node.js from nodejs.org
2. Get TestRail API key from your TestRail settings
3. Install the server: npm install -g testrail-mcp-server
4. Configure your AI assistant with your TestRail credentials
5. Restart your AI assistant and start asking questions!

Prerequisites

You need these tools before installing:

1. Node.js 18.17.0+ - Download from nodejs.org (LTS version)
2. npm - Comes with Node.js automatically
3. AI Assistant - Cursor (cursor.sh) or Claude Desktop (claude.ai)
4. TestRail Account - With API access enabled

Verify installation:

Getting TestRail API Credentials

1. Log into TestRail at your instance URL (e.g., https://yourcompany.testrail.com)
2. Get API Key:
   • Click your profile picture → "My Settings"
   • Scroll to "API Keys" section
   • Click "Add API Key"
   • Name it (e.g., "MCP Server")
   • Copy and save the API key securely
3. Note your credentials:
   • Username: Your TestRail login (usually email)
   • URL: Your TestRail web address

Installation

Step 1: Install the Server

Open Command Prompt/Terminal and run:

Step 2: Configure Your AI Assistant

For Cursor Users:

1. Open Cursor → Settings (Ctrl + , or Cmd + ,)
2. Find "MCP" settings
3. Add this configuration:

For Claude Desktop Users:

1. Find config file:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the same configuration as above

Replace these values:

• your_testrail_username: Your TestRail login (usually email)
• your_testrail_api_key: The API key from TestRail
• https://your-instance.testrail.com: Your TestRail URL

Step 3: Restart and Test

1. Restart your AI assistant completely
2. Test: Ask "Can you show me my TestRail projects?"

Usage

Once set up, simply talk to your AI assistant naturally:

Viewing Information:

• "Show me all my TestRail projects"
• "What test cases are in project 1?"
• "Show me test case number 123"

Updating Tests:

• "Update test case 123 with the title 'Login functionality test'"
• "Change the priority of test case 456 to high"
• "Add a comment to test case 789"

Adding Results:

• "Mark test 456 as passed"
• "Add a failed result to test 789 with comment 'Button not clickable'"
• "Upload this screenshot to test case 123"

Searching:

• "Find all test cases with 'login' in the title"
• "Show me failed tests from the last test run"

Troubleshooting

"Command not found" or "npm is not recognized"

• Install Node.js from nodejs.org
• Restart Command Prompt/Terminal
• Check with node --version

"Authentication failed" or "Invalid credentials"

• Verify your TestRail username (usually email)
• Copy API key again from TestRail
• Check TestRail URL starts with https://

"Connection timeout" or "Cannot connect to TestRail"

• Check internet connection
• Verify TestRail URL is correct
• Test TestRail in web browser

AI assistant doesn't respond to TestRail questions

• Restart your AI assistant completely
• Check configuration file format (valid JSON)
• Verify all required fields are filled

"Permission denied" error

• Run Command Prompt as Administrator (Windows) or with sudo (Mac/Linux)
• Update to latest Node.js version

Still having trouble?

• Check error messages for clues
• Try installation steps again
• Create an issue on GitHub with your error details

Security Best Practices

• Never share your API key - treat it like a password
• Use HTTPS URLs - ensure your TestRail URL starts with https://
• Don't put API keys in code - always use configuration files
• Rotate API keys regularly - change them every few months
• Keep TestRail account secure - use strong passwords and 2FA

What NOT to do:

• Don't share configuration files with others
• Don't put API keys in public repositories
• Don't use HTTP URLs (only HTTPS)
• Don't share screenshots showing your API key

Additional Resources

Helpful Links:

• TestRail API Documentation
• Cursor MCP Documentation
• Claude Desktop Setup Guide

Getting Support:

• GitHub Issues - Report bugs or ask questions
• Contact your TestRail administrator for API access issues

License

MIT License - see LICENSE file for details.