Skip to main content
Glama
TestRail MCP Server

TestRail MCP Server

by Derrbal

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.

Related MCP server: TestRail MCP Server

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:

node --version  # Should show 18.17.0 or higher
npm --version   # Should show a version number

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:

npm install -g testrail-mcp-server

Step 2: Configure Your AI Assistant

For Cursor Users:

  1. Open Cursor → Settings (Ctrl + , or Cmd + ,)

  2. Find "MCP" settings

  3. 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:

  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:

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.

Available Tools

18 tools
add_attachment_to_caseAdd Attachment to TestRail CaseC

Upload a file attachment to a TestRail test case.

Inputs: case_id (required), file_path (required).

add_caseAdd TestRail CaseA

Create a new TestRail test case in a specific section. IMPORTANT: Before creating a case, gather required information using get_projects, get_suites, get_sections, and get_case_fields tools to ensure proper section_id, type_id, and custom field values. Or ask the user to provide the information if not provided.

Inputs: title (required), section_id (required), type_id, priority_id, +2 more.

add_resultAdd TestRail ResultC

Adds a new test result, comment, or assigns a test.

Inputs: test_id (required), status_id (required), comment, version, +5 more.

get_caseGet TestRail CaseC

Fetch a TestRail test case by ID.

Inputs: case_id (required).

get_case_fieldsGet TestRail Case FieldsB

Returns a list of available test case custom fields.

Inputs: no named parameters.

get_casesGet TestRail CasesB

Get a list of test cases for a project or specific test suite with optional filtering and pagination.

Inputs: project_id (required), suite_id, created_after, created_before, +14 more.

get_projectGet TestRail ProjectB

Get details for a specific TestRail project by ID.

Inputs: project_id (required).

get_projectsGet TestRail ProjectsB

List all TestRail projects.

Inputs: no named parameters.

get_runGet TestRail RunB

Returns an existing test run. Please see get tests for the list of included tests in this run.

Inputs: run_id (required).

get_runsGet TestRail RunsA

Get a list of test runs for a project with optional filtering and pagination. Only returns test runs that are not part of a test plan.

Inputs: project_id (required), created_after, created_before, created_by, +6 more.

get_sectionsGet TestRail SectionsC

Get a list of sections for a project and test suite with optional pagination.

Inputs: project_id (required), suite_id, limit, offset.

get_suiteGet TestRail SuiteC

Get details for a specific TestRail test suite by ID.

Inputs: suite_id (required).

get_suitesGet TestRail SuitesB

Get all test suites for a specific TestRail project by ID.

Inputs: project_id (required).

get_testGet TestRail TestC

Returns an existing test.

Inputs: test_id (required), with_data.

get_testsGet TestRail TestsC

Returns a list of tests for a test run.

Inputs: run_id (required), status_id, limit, offset, +1 more.

update_caseUpdate TestRail CaseC

Update a TestRail test case by ID with new field values.

Inputs: case_id (required), title, section_id, type_id, +3 more.

update_runUpdate TestRail RunC

Updates an existing test run. Partial updates are supported.

Inputs: run_id (required), name, description, milestone_id, +8 more.

update_testUpdate TestRail TestC

Updates the labels assigned to an existing test.

Inputs: test_id (required), labels, custom.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific TestRail resources (cases, runs, tests, projects, suites, sections, fields), but there is some overlap between get_case/get_cases and get_test/get_tests that could cause confusion if an agent misinterprets singular vs. plural usage. The descriptions help clarify, but the naming similarity creates minor ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case, using clear action verbs like get, add, and update paired with specific nouns (e.g., get_case, add_attachment_to_case, update_run). This uniformity makes the tool set predictable and easy to navigate.

    Tool Count4/5

    With 18 tools, the count is slightly high but reasonable for a comprehensive TestRail API coverage, including CRUD operations for cases, runs, tests, and supporting resources like projects and suites. It feels slightly heavy but well-scoped to the domain without being excessive.

    Completeness5/5

    The tool set provides complete CRUD/lifecycle coverage for TestRail's core domain, including projects, suites, sections, cases, runs, tests, and attachments. It supports creation (add_case), retrieval (get_* tools), updates (update_* tools), and result management (add_result), with no obvious gaps for essential workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact directly with TestRail instances for managing test projects, suites, cases, runs, results, plans, milestones, and attachments through the TestRail API with secure authentication.
      77
      55 npm
      1
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Enables management of TestRail projects, test cases, runs, and results directly through MCP-supported clients. It provides a comprehensive set of tools to interact with the TestRail API for seamless test cycle management within AI environments.
      42
      6,218 npm
      42
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with TestRail test management system, supporting full CRUD operations on projects, suites, sections, test cases, runs, results, plans, and milestones.
      35
      327 npm
      1
      MIT