TestRail
AI-native Model Context Protocol (MCP) server for TestRail. Lets Claude, Cursor, Windsurf, and other AI assistants browse projects, create and update test cases, kick off test runs, and record results through natural-language conversation — with stro
What is TestRail?
TestRail is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to ai-native model context protocol (mcp) server for testrail. lets claude, cursor, windsurf, and other ai assistants browse projects, create and update test cases, kick off test runs, and record results...
AI-native Model Context Protocol (MCP) server for TestRail. Lets Claude, Cursor, Windsurf, and other AI assistants browse projects, create and update test cases, kick off test runs, and record results through natural-language conversation — with stro
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- AI-native Model Context Protocol (MCP) server for TestRail.
Use Cases
Maintainer
Works with
Installation
NPM
npx -y @uarlouski/testrail-mcp-serverManual Installation
npx -y @uarlouski/testrail-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use TestRail
The TestRail MCP Server is an AI-native integration that lets Claude, Cursor, Windsurf, and other MCP-compatible clients control TestRail through natural language conversation. It exposes 20+ tools for browsing projects and suites, creating and updating test cases with custom fields and templates, kicking off test runs, recording results, attaching files, and managing shared steps — covering the full QA workflow without requiring manual UI navigation. QA engineers and developers can use it to automate test case generation from requirements, rapidly triage failing runs, and report results directly from their AI assistant.
Prerequisites
- A TestRail account with API access enabled (cloud or self-hosted instance)
- A TestRail API key generated from My Settings → API Keys in the TestRail UI
- Node.js 18+ installed (the server is TypeScript/Node-based)
- npx available to run the npm package
- An MCP-compatible client such as Claude Desktop, Cursor, or Windsurf
Generate a TestRail API key
Log in to TestRail, go to My Settings → API Keys, and generate a new API key. Copy it for use in the MCP configuration.
Add the server to your MCP client configuration
Edit your client's MCP config file with the TestRail server package and your three required credentials. On Claude Desktop (macOS), the file is ~/Library/Application Support/Claude/claude_desktop_config.json.
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@uarlouski/testrail-mcp-server"],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your_api_key_here"
}
}
}
}Restart your MCP client
Restart Claude Desktop or your chosen MCP client so it loads the TestRail server and its 20+ tools.
Enable shared steps (optional)
If your TestRail instance uses shared steps, add TESTRAIL_ENABLE_SHARED_STEPS=true to the env block to unlock the shared step management tools.
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@uarlouski/testrail-mcp-server"],
"env": {
"TESTRAIL_INSTANCE_URL": "https://your-instance.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your_api_key_here",
"TESTRAIL_ENABLE_SHARED_STEPS": "true"
}
}
}
}Verify the connection by browsing projects
Ask Claude to list all active TestRail projects. This confirms the server is connected and credentials are valid.
TestRail Examples
Client configuration
Complete Claude Desktop configuration for the TestRail MCP server with all required environment variables.
{
"mcpServers": {
"testrail": {
"command": "npx",
"args": ["-y", "@uarlouski/testrail-mcp-server"],
"env": {
"TESTRAIL_INSTANCE_URL": "https://yourcompany.testrail.io",
"TESTRAIL_USERNAME": "[email protected]",
"TESTRAIL_API_KEY": "your_testrail_api_key_here"
}
}
}
}Prompts to try
Sample QA workflow prompts covering test case management, run creation, and result recording.
- "List all active projects and show me the most recently updated one"
- "Show me all test cases in section 5 of project 3"
- "Create a test case for Login Validation with steps for valid credentials, invalid password, and account lockout"
- "Start a new test run for project 2 suite 1 and name it 'Sprint 42 Regression'"
- "Mark test case 1042 as passed in the current test run"
- "Find all failed test cases from the last run and generate a bug report summary"Troubleshooting TestRail
Authentication fails with 401 Unauthorized errors
Verify all three credentials in the config: TESTRAIL_INSTANCE_URL must include the full domain (https://yourcompany.testrail.io), TESTRAIL_USERNAME must be your login email, and TESTRAIL_API_KEY must be the API key from My Settings → API Keys, not your login password.
Shared step tools are not available or throw errors
Shared steps must be explicitly enabled by adding TESTRAIL_ENABLE_SHARED_STEPS=true to the env block. Also verify your TestRail plan includes the shared steps feature — it may not be available on all subscription tiers.
Large test suite results are cut off or cause token limit issues
The server can optionally write large result sets to disk to bypass context window limits. Ask Claude to save the results to a file rather than returning them all inline, or narrow the query by filtering to a specific section or priority.
Frequently Asked Questions about TestRail
What is TestRail?
TestRail is a Model Context Protocol (MCP) server that ai-native model context protocol (mcp) server for testrail. lets claude, cursor, windsurf, and other ai assistants browse projects, create and update test cases, kick off test runs, and record results through natural-language conversation — with stro It connects AI assistants to external tools and data sources through a standardized interface.
How do I install TestRail?
Install via npm with the command: npx -y @uarlouski/testrail-mcp-server. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with TestRail?
TestRail works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is TestRail free to use?
Yes, TestRail is open source and available under the Apache 2.0 license. You can use it freely in both personal and commercial projects.
TestRail Alternatives — Similar Developer Tools Servers
Looking for alternatives to TestRail? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up TestRail in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use TestRail?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.