testrails-mcp
Supports converting Jira tickets into TestRail test cases by extracting acceptance criteria and creating cases, with a confirmation step before creation.
Provides CRUD operations for TestRail test cases, test runs, and results, enabling management of test projects, suites, sections, and recording test outcomes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@testrails-mcp List all projects in TestRail"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
testrails-mcp
An MCP (Model Context Protocol) server that exposes TestRail CRUD operations to agentic coding tools like Claude Code and Codex CLI, plus a bundled agent skill for turning Jira tickets into TestRail cases.
What it does
testrails-mcp is a thin, async wrapper around the TestRail API v2. Once
registered with your agent, it lets the model:
Navigate your TestRail instance — list projects, suites, and sections.
Manage test cases — list, read, create, update, and (soft-)delete cases.
Manage runs — list, read, create, and close test runs; list the tests inside a run.
Record results — add and read results for cases within a run.
It speaks stdio (the standard MCP transport for local tools), authenticates
with TestRail via HTTP Basic auth using your email and API key, and reads
credentials from environment variables or a local .env file.
The repo also ships a portable agent skill (skills/jira-to-testrail/) that
auto-triggers when a user asks to convert a Jira ticket into TestRail cases.
The skill orchestrates a Jira MCP (any vendor) + this MCP to produce one case
per acceptance criterion, with a confirmation gate before anything is created.
Related MCP server: TestRail MCP Server
Requirements
Python 3.11+
A TestRail account with API access enabled (admin → Site Settings → API)
A TestRail API key — generate one at My Settings → API Keys → Add Key
An agent runtime that speaks MCP — Claude Code, Codex CLI, Claude Desktop, or any other MCP-compatible client
Setup
git clone <this-repo> testrails-mcp
cd testrails-mcp
uv venv
uv pip install -e .
cp .env.example .env
# then edit .env with your TestRail URL, email, and API key.env shape:
TESTRAIL_URL=https://yourcompany.testrail.io
TESTRAIL_USER=you@example.com
TESTRAIL_API_KEY=...Verify it launches:
.venv/bin/testrails-mcp
# (should sit silently waiting on stdin; Ctrl+C to exit)Confirm the protocol surface:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | .venv/bin/testrails-mcpFor an interactive smoke test with form inputs for every tool:
npx @modelcontextprotocol/inspector .venv/bin/testrails-mcpRegister with your agent
Claude Code
claude mcp add testrails -- /absolute/path/to/.venv/bin/testrails-mcpOr add to ~/.claude.json (user-scope) or .mcp.json (project-scope):
{
"mcpServers": {
"testrails": {
"command": "/absolute/path/to/.venv/bin/testrails-mcp"
}
}
}Codex CLI
Add to ~/.codex/config.toml:
[mcp_servers.testrails]
command = "/absolute/path/to/.venv/bin/testrails-mcp"Other clients (Claude Desktop, etc.)
Use the standard MCP server entry: command =
/absolute/path/to/.venv/bin/testrails-mcp, no args.
Tools
Navigation
list_projects()list_suites(project_id)list_sections(project_id, suite_id?)
Cases (CRUD)
list_cases(project_id, suite_id?, section_id?, limit?, offset?)get_case(case_id)add_case(section_id, title, type_id?, priority_id?, estimate?, refs?, custom_fields?)update_case(case_id, title?, type_id?, priority_id?, estimate?, refs?, custom_fields?)delete_case(case_id, soft=True)—soft=Truepreviews; passsoft=Falseto actually delete
Runs
list_runs(project_id)get_run(run_id)add_run(project_id, name, suite_id?, description?, case_ids?, include_all?)close_run(run_id)list_tests(run_id)
Results
add_result_for_case(run_id, case_id, status_id, comment?, version?, elapsed?, defects?)get_results_for_case(run_id, case_id)
TestRail default status IDs: 1=Passed, 2=Blocked, 3=Untested, 4=Retest, 5=Failed.
custom_fields on add_case / update_case accepts any TestRail custom field
the instance has configured — commonly custom_steps, custom_preconds,
custom_expected, or custom_steps_separated.
Skills
This repo ships one bundled skill — a portable SKILL.md that works in both
Claude Code and Codex CLI. Skills are auto-loaded by the agent based on their
description and activate when the user's prompt matches.
jira-to-testrail
Converts a Jira ticket into TestRail test cases. Triggers on phrases like:
"Turn PROJ-1234 into test cases"
"Create TestRail cases from this ticket"
"Generate QA coverage for "
What it does:
Verifies both a Jira MCP and this TestRail MCP are connected.
Reads the ticket, extracts acceptance criteria (refuses to invent any).
Auto-discovers the instance's custom-field shape by sampling an existing case in the target section.
Drafts one case per AC with behavior-focused titles and mapped priority.
Shows you the plan and waits for confirmation before creating.
Creates the cases and reports IDs + URLs as a table.
On partial failure, asks how to proceed rather than auto-retrying.
Requires a Jira MCP to also be installed (e.g. Atlassian's official MCP, or
mcp-atlassian) — the skill is vendor-agnostic about which one.
Installing the skill
Skills live in a directory the agent watches. Symlink the bundled skill into
your agent's skills location so git pull keeps it up to date:
Claude Code
mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/jira-to-testrail" ~/.claude/skills/jira-to-testrailCodex CLI
mkdir -p ~/.agents/skills
ln -s "$(pwd)/skills/jira-to-testrail" ~/.agents/skills/jira-to-testrailProject-scoped (Codex only)
If you'd rather scope the skill to a single repo, drop a copy into that repo's
.agents/skills/ directory — Codex walks up from the cwd to find skills.
Prefer a copy over a symlink:
cp -r skills/jira-to-testrail ~/.claude/skills/ # or ~/.agents/skills/Verifying the skill loaded
Claude Code: run
/skillsand look forjira-to-testrailin the list.Codex CLI: start a new session and ask "what skills do you have?" — it should mention
jira-to-testrail(Codex loads skill names/descriptions at session start).
If it doesn't show up, double-check:
The symlink target exists (
ls -la ~/.claude/skills/jira-to-testrail).SKILL.mdis directly inside that folder, not nested further.The frontmatter (
name,description) is present and valid YAML.
Project layout
testrails_mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/testrails_mcp/
│ ├── __init__.py
│ ├── client.py # async httpx client (Basic auth)
│ └── server.py # FastMCP tools, stdio entrypoint
└── skills/
└── jira-to-testrail/
└── SKILL.md # portable Claude/Codex skillTroubleshooting
Missing TestRail credentialson startup —.envnot found or missing a key. The server reads.envfrom the cwd it's launched in; if your agent spawns it from a different directory, set the vars in your shell profile or agent config instead.TestRail API 401— wrong email or API key. Confirm the key in My Settings → API Keys and that the user has API access on the instance.TestRail API 403on create/update/delete — the user lacks write permission on the project, suite, or section.delete_casereturns a preview — that's the default (soft=True). Passsoft=Falseto actually delete.Skill doesn't trigger — descriptions are matched fuzzily, but very short prompts may miss. Try a phrase closer to the examples in the skill's description. As a fallback you can invoke it explicitly (
/skill jira-to-testrailin Codex; mention the skill name directly in Claude Code).
Roadmap
Phase 1 (current): Cases, Runs, Results, plus the Jira → TestRail skill.
Likely next:
Sections CRUD (so the skill can create new sections if needed).
Milestones and Plans.
A
bulk_add_result_for_casestool (TestRail has a native batch endpoint).A second skill for bug report → regression case flows.
License
MIT.
Available Tools
15 toolsadd_caseC
Create a new test case in a section.
custom_fields: pass TestRail custom fields like {"custom_steps": "..."}
Inputs: section_id (required), title (required), type_id, priority_id, +3 more.
add_result_for_caseC
Add a result for a case within a run.
status_id: 1=Passed, 2=Blocked, 3=Untested, 4=Retest, 5=Failed (TestRail defaults).
Inputs: run_id (required), case_id (required), status_id (required), comment, +3 more.
add_runB
Create a test run. If case_ids is provided, include_all defaults to False.
Inputs: project_id (required), name (required), suite_id, description, +2 more.
close_runA
Close a test run (archives it; cannot be reopened).
Inputs: run_id (required).
delete_caseC
Delete a test case. soft=True previews the deletion without applying it.
Inputs: case_id (required), soft.
get_caseA
Get a single test case by id.
Inputs: case_id (required).
get_results_for_caseC
Get all results recorded for a case in a given run.
Inputs: run_id (required), case_id (required).
get_runB
Get a single test run by id.
Inputs: run_id (required).
list_casesB
List test cases in a project. Filter by suite and/or section.
Inputs: project_id (required), suite_id, section_id, limit, +1 more.
list_projectsA
List all TestRail projects.
Inputs: no named parameters.
list_runsC
List test runs for a project.
Inputs: project_id (required).
list_sectionsA
List sections in a project (optionally filtered by suite).
Inputs: project_id (required), suite_id.
list_suitesC
List test suites for a project.
Inputs: project_id (required).
list_testsC
List tests (case-instances) inside a run.
Inputs: run_id (required).
update_caseA
Update an existing test case. Only provided fields are changed.
Inputs: case_id (required), title, type_id, priority_id, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct TestRail entity or action (project, suite, section, case, run, result, test) with clear boundaries, e.g., add_case vs update_case, list_cases vs get_case, add_result_for_case vs get_results_for_case. No two tools have overlapping purposes.
All tools follow a consistent verb_noun pattern using snake_case (e.g., add_case, get_run, list_sections). Verbs are imperative (add, get, list, delete, close, update) and nouns are singular entity names. Minor prepositions like 'for_case' are uniform.
Fifteen tools is well-scoped for a TestRail MCP covering core entities: projects, suites, sections, cases, runs, results, and tests. Each tool serves a clear purpose without unnecessary bloat or missing essentials.
The tool set provides full CRUD for test cases and runs, plus read and list operations for most entities. However, missing create/update/delete for sections and suites are notable gaps that agents would need to work around, though core test workflow is covered.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Test management for AI agents: cases, runs, results, cycles and traceability.
Related MCP Servers
- AlicenseAqualityFmaintenanceEnables 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.426,218 npm42MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for TestRail that enables AI assistants to interact with TestRail's test management platform. It can query and manage projects, test cases, runs, results, plans, milestones, and more.MIT
- AlicenseBqualityCmaintenanceAn MCP server for TestRail that prepares everything needed to generate test cases from Jira tickets, Confluence pages, or free-form specs and pushes them back to TestRail.3143 PyPI2MIT
- AlicenseCqualityDmaintenanceMCP server for TestRail API, providing AI assistants with 107 tools to manage test cases, runs, results, plans, and more. Supports API key, password, and SSO cookie authentication.5418 npm2MIT