Skip to content

g-tiwari/mcp-testrail

BranchesTags

Repository files navigation

@g-tiwari/mcp-testrail

MCP server for the TestRail API. Gives AI assistants full access to manage test cases, runs, results, plans, and all other TestRail resources.

107 tools covering every TestRail API endpoint, with toolset filtering for token efficiency.

Works with any TestRail setup — standard cloud/self-hosted instances (API key or password auth) and enterprise SSO deployments (SAML/OIDC cookie-based auth).

Quick Start

Add to your MCP client config (Claude Desktop, Claude Code, Kiro, Cursor, Windsurf — see IDE Configuration below):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

That's it. Restart your MCP client and start asking it to manage TestRail.

Enterprise SSO? Replace the API key env vars with "TESTRAIL_COOKIE_PATH": "~/path/to/cookies.txt" — see Authentication for all options. You can also add optional env vars like TESTRAIL_PROJECT_IDS, TESTRAIL_TOOLSETS, and TESTRAIL_READ_ONLY_MODE to the same env block — see Environment Variables.

Authentication

Option 1: API Key (Recommended for most users)

This is the standard auth method for TestRail Cloud and self-hosted instances.

  1. Go to My Settings in TestRail (top-right menu)
  2. Enable the API under API section
  3. Generate an API key

Set these environment variables:

TESTRAIL_URL=https://yourcompany.testrail.com
TESTRAIL_EMAIL=your@email.com
TESTRAIL_API_KEY=your-api-key

Option 2: Password

For instances where API keys are not available.

TESTRAIL_URL=https://yourcompany.testrail.com
TESTRAIL_EMAIL=your@email.com
TESTRAIL_PASSWORD=your-password

Option 3: SSO Cookie Auth (Enterprise)

For enterprise TestRail instances behind SSO providers (Okta, Azure AD, etc.). The server reads a Netscape-format cookie file, automatically completes the SAML/OIDC login flow, and obtains a TestRail session.

TESTRAIL_URL=https://testrail.yourcompany.com
TESTRAIL_COOKIE_PATH=~/path/to/sso/cookies.txt

How it works: The server loads SSO cookies from the file, hits the TestRail SSO redirect endpoint, parses the SAML response form, and submits it back to TestRail to obtain a tr_session cookie. It also hot-reloads when the cookie file changes (e.g. after re-authenticating with your SSO provider).

Note: You may need to refresh your SSO cookies periodically (e.g. re-authenticate via your SSO provider's CLI).

Option 4: SSO Cookie + API Key (Hybrid)

For enterprise setups where the SSO proxy requires cookies and TestRail also validates API key auth.

TESTRAIL_URL=https://testrail.yourcompany.com
TESTRAIL_COOKIE_PATH=~/path/to/sso/cookies.txt
TESTRAIL_EMAIL=your@email.com
TESTRAIL_API_KEY=your-api-key

IDE / AI Assistant Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

API Key auth:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

SSO Cookie auth (enterprise):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://testrail.yourcompany.com",
        "TESTRAIL_COOKIE_PATH": "~/path/to/sso/cookies.txt"
      }
    }
  }
}

Claude Code (CLI)

Add to ~/.claude/settings.json or your project's .claude/settings.json:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json in your project root:

API Key auth:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

SSO Cookie auth (enterprise):

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://testrail.yourcompany.com",
        "TESTRAIL_COOKIE_PATH": "~/path/to/sso/cookies.txt"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["-y", "@g-tiwari/mcp-testrail"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Local Development

For local testing (not published to npm), use the absolute path to the built file:

{
  "mcpServers": {
    "testrail": {
      "command": "node",
      "args": ["/absolute/path/to/testrail-mcp/build/src/index.js"],
      "env": {
        "TESTRAIL_URL": "https://yourcompany.testrail.com",
        "TESTRAIL_EMAIL": "your@email.com",
        "TESTRAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

Variable Required Description
TESTRAIL_URL Yes TestRail instance URL (e.g. https://yourcompany.testrail.com)
TESTRAIL_EMAIL For API key/password auth User email address
TESTRAIL_API_KEY Option 1 API key (from My Settings in TestRail)
TESTRAIL_PASSWORD Option 2 Password (if API keys are unavailable)
TESTRAIL_COOKIE_PATH Option 3 Path to Netscape-format cookie file
TESTRAIL_TOOLSETS No Comma-separated toolset names or "all" (default: core toolsets)
TESTRAIL_TOOLS No Additional individual tool names to enable
TESTRAIL_DENIED_TOOLS_REGEX No Regex pattern to exclude tools by name
TESTRAIL_PROJECT_IDS No Comma-separated project IDs to scope the server to (e.g. "5" or "1,5,12")
TESTRAIL_READ_ONLY_MODE No Set to "true" to expose only read operations

If both TESTRAIL_API_KEY and TESTRAIL_PASSWORD are set, API key takes precedence.

Project Scoping

Use TESTRAIL_PROJECT_IDS to restrict the server to specific projects. This is useful when your TestRail instance has many projects but you only work with a few.

Configuration Description hints Auto-inject project_id Restrict
Unset None No No
Single ID ("5") [Project 5] appended to tool descriptions Yes — fills missing project_id Rejects other IDs
Multiple IDs ("1,5,12") [Allowed projects: 1, 5, 12] appended No — LLM must pick Rejects other IDs 
# Scope to a single project (auto-injects project_id)
TESTRAIL_PROJECT_IDS="5"

# Scope to multiple projects (LLM must specify which)
TESTRAIL_PROJECT_IDS="1,5,12"

Tools like get_projects (no project_id input) and add_project (creates new) are unaffected. Entity-scoped tools like get_case (which take a case_id, not project_id) are also unaffected.

Toolsets

Tools are organized into 18 toolsets. 9 are enabled by default (54 tools) to keep token usage low. Use TESTRAIL_TOOLSETS to customize.

Toolset Default Tools Description
projects Yes 5 Project CRUD
suites Yes 5 Suite CRUD
sections Yes 6 Section CRUD + move
cases Yes 13 Case CRUD + bulk + fields/types
runs Yes 6 Run CRUD + close
tests Yes 2 Read tests in runs
results Yes 8 Result CRUD + bulk + fields
users Yes 5 User lookup + roles
metadata Yes 4 Priorities, statuses, templates
plans No 12 Test plan management
milestones No 5 Milestone CRUD
groups No 5 Group management
attachments No 8 File attachments
configurations No 7 Test configurations
reports No 2 Report execution
shared_steps No 5 Shared steps
variables No 4 Variables
datasets No 5 Datasets

Toolset Examples

# Only case and result management (21 tools)
TESTRAIL_TOOLSETS="cases,results"

# Everything (107 tools)
TESTRAIL_TOOLSETS="all"

# Default toolsets + specific additional tools
TESTRAIL_TOOLS="get_plan,get_plans,get_milestones"

# Block all destructive operations
TESTRAIL_DENIED_TOOLS_REGEX="^(delete_|close_)"

# Read-only mode (~40 tools)
TESTRAIL_READ_ONLY_MODE="true"

Token Efficiency

Every MCP tool definition is injected into the LLM context on every conversation turn. More tools = more tokens burned before the model even reads your message. This MCP is designed to keep that cost low.

Default config uses ~2,000 tokens for tool definitions — roughly half of what exposing all 107 tools would cost (~4,000 tokens). Over a 10-turn conversation, that's ~20,000 tokens saved.

Configuration Tools ~Tokens per turn
Default (9 core toolsets) 54 ~2,000
Read-only mode 46 ~1,700
Custom (e.g. cases,results) 21 ~800
All toolsets 107 ~4,000

How

  • Toolset filtering — only 54 of 107 tools exposed by default; non-essential toolsets (plans, milestones, groups, etc.) are opt-in
  • Compact descriptions — average 24 characters per tool (5-10 words), not full sentences
  • Bulk operations — add_results, update_cases, delete_cases accept arrays, so one call replaces dozens of round-trips (each avoided round-trip saves the full tool list re-injection)
  • Max pagination — defaults to 250 items per page (TestRail's maximum), fewer calls needed
  • Raw JSON responses — no metadata envelope or wrapper overhead; delete/close operations return just {"success": true}
  • Layered filtering — TESTRAIL_TOOLSETS → TESTRAIL_TOOLS → TESTRAIL_READ_ONLY_MODE → TESTRAIL_DENIED_TOOLS_REGEX all compose, so you can tune to exactly what you need

Rate Limiting

Automatic retry with exponential backoff on HTTP 429 responses. Respects the Retry-After header. Max 3 retries.

Available Tools (107)

Click to expand full tool list

Projects (5)

  • get_project — Get a project by ID
  • get_projects — List all projects
  • add_project — Create a new project
  • update_project — Update an existing project
  • delete_project — Delete a project by ID

Suites (5)

  • get_suite — Get a test suite by ID
  • get_suites — List suites for a project
  • add_suite — Create a test suite
  • update_suite — Update a test suite
  • delete_suite — Delete a test suite

Sections (6)

  • get_section — Get a section by ID
  • get_sections — List sections in a project/suite
  • add_section — Create a section
  • move_section — Move a section to a new parent
  • update_section — Update a section
  • delete_section — Delete a section

Cases (13)

  • get_case — Get a test case by ID
  • get_cases — List test cases with filters
  • get_history_for_case — Get change history for a case
  • add_case — Create a test case in a section
  • update_case — Update a test case
  • update_cases — Bulk update multiple test cases
  • delete_case — Delete a test case
  • delete_cases — Bulk delete multiple test cases
  • copy_cases_to_section — Copy cases to another section
  • move_cases_to_section — Move cases to another section
  • get_case_fields — List available case fields
  • add_case_field — Create a custom case field
  • get_case_types — List available case types

Runs (6)

  • get_run — Get a test run by ID
  • get_runs — List test runs for a project
  • add_run — Create a test run
  • update_run — Update a test run
  • close_run — Close a test run
  • delete_run — Delete a test run

Tests (2)

  • get_test — Get a test by ID
  • get_tests — List tests in a run

Results (8)

  • get_results — Get results for a test
  • get_results_for_case — Get results for a case in a run
  • get_results_for_run — Get all results for a run
  • add_result — Add a result for a test
  • add_result_for_case — Add a result for a case in a run
  • add_results — Bulk add results for a run
  • add_results_for_cases — Bulk add results by case for a run
  • get_result_fields — List available result fields

Plans (12)

  • get_plan — Get a test plan by ID
  • get_plans — List test plans for a project
  • add_plan — Create a test plan
  • add_plan_entry — Add a suite entry to a plan
  • add_run_to_plan_entry — Add a run to a plan entry
  • update_plan — Update a test plan
  • update_plan_entry — Update a plan entry
  • update_run_in_plan_entry — Update a run in a plan entry
  • close_plan — Close a test plan
  • delete_plan — Delete a test plan
  • delete_plan_entry — Delete a plan entry
  • delete_run_from_plan_entry — Delete a run from a plan entry

Milestones (5)

  • get_milestone — Get a milestone by ID
  • get_milestones — List milestones for a project
  • add_milestone — Create a milestone
  • update_milestone — Update a milestone
  • delete_milestone — Delete a milestone

Users & Roles (5)

  • get_user — Get a user by ID
  • get_current_user — Get the authenticated user
  • get_user_by_email — Find a user by email
  • get_users — List users
  • get_roles — List available user roles

Groups (5)

  • get_group — Get a group by ID
  • get_groups — List all groups
  • add_group — Create a user group
  • update_group — Update a user group
  • delete_group — Delete a user group

Attachments (8)

  • add_attachment_to_plan — Attach a file to a test plan
  • add_attachment_to_result — Attach a file to a result
  • add_attachment_to_run — Attach a file to a run
  • add_attachment_to_case — Attach a file to a case
  • get_attachments_for_case — List attachments for a case
  • get_attachments_for_run — List attachments for a run
  • get_attachment — Get attachment metadata by ID
  • delete_attachment — Delete an attachment

Configurations (7)

  • get_configs — List configurations for a project
  • add_config_group — Create a configuration group
  • add_config — Add a config to a group
  • update_config_group — Update a configuration group
  • update_config — Update a configuration
  • delete_config_group — Delete a configuration group
  • delete_config — Delete a configuration

Metadata (4)

  • get_priorities — List available priorities
  • get_statuses — List available test statuses
  • get_case_statuses — List available case statuses
  • get_templates — List templates for a project

Reports (2)

  • get_reports — List reports for a project
  • run_report — Execute a report template

Shared Steps (5)

  • get_shared_step — Get a shared step by ID
  • get_shared_steps — List shared steps for a project
  • add_shared_step — Create a shared step
  • update_shared_step — Update a shared step
  • delete_shared_step — Delete a shared step

Variables (4)

  • get_variables — List variables for a project
  • add_variable — Create a variable
  • update_variable — Update a variable
  • delete_variable — Delete a variable

Datasets (5)

  • get_dataset — Get a dataset by ID
  • get_datasets — List datasets for a project
  • add_dataset — Create a dataset
  • update_dataset — Update a dataset
  • delete_dataset — Delete a dataset

Troubleshooting

"Authentication failed: invalid or missing user/password or session cookie"

  • API Key auth: Verify your API key is correct and the API is enabled in TestRail (Administration > Site Settings > API).
  • SSO Cookie auth: Your SSO cookies may have expired. Refresh them (re-authenticate with your SSO provider) and try again. The server auto-detects cookie file changes.

"TESTRAIL_URL environment variable is required"

Ensure TESTRAIL_URL is set in your MCP config's env block. The URL should not have a trailing slash.

SSO login flow fails

  1. Ensure your SSO cookies are fresh and valid
  2. Test by opening your TestRail URL in a browser — if you can access it, the cookies should work
  3. Check that TESTRAIL_COOKIE_PATH points to the correct Netscape-format cookie file
  4. The server logs to stderr — check your MCP client's logs for detailed SSO flow output

Tools not appearing

Check TESTRAIL_TOOLSETS — by default only 9 core toolsets (54 tools) are enabled. Use TESTRAIL_TOOLSETS="all" for all 107 tools.

License

MIT

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 Latest
Mar 1, 2026

Packages

 
 
 

Contributors

Languages