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
- Install Node.js from nodejs.org
- Get TestRail API key from your TestRail settings
- Install the server:
npm install -g testrail-mcp-server - Configure your AI assistant with your TestRail credentials
- Restart your AI assistant and start asking questions!
Prerequisites
You need these tools before installing:
- Node.js 18.17.0+ - Download from nodejs.org (LTS version)
- npm - Comes with Node.js automatically
- AI Assistant - Cursor (cursor.sh) or Claude Desktop (claude.ai)
- TestRail Account - With API access enabled
Verify installation:
node --version # Should show 18.17.0 or higher
npm --version # Should show a version number
Getting TestRail API Credentials
-
Log into TestRail at your instance URL (e.g.,
https://yourcompany.testrail.com) -
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
-
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:
npm install -g testrail-mcp-server
Step 2: Configure Your AI Assistant
For Cursor Users:
- Open Cursor → Settings (
Ctrl + ,orCmd + ,) - Find "MCP" settings
- Add this 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"
}
}
}
}
For Claude Desktop Users:
- Find config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - Mac:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
- 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 TestRailhttps://your-instance.testrail.com: Your TestRail URL
Step 3: Restart and Test
- Restart your AI assistant completely
- 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:
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.