allure-testops-mcp
An MCP server for Allure TestOps that lets an LLM explore projects, launches, test cases, results, and reference data through the Allure REST API.
Discover all projects across the instance and use any
project_idwithout reconfiguration.View project statistics: test-case counts, automation rate, and latest closed launch pass/fail breakdown.
List recent launches and inspect test results, optionally filtered by status, with pagination.
Search FAILED/BROKEN tests in the latest or a specified launch.
Browse test cases with automated/manual and owner filters; read full test-case detail, scenario steps, and custom-field values.
List project statuses, layers, and custom fields; README also documents category and category-matcher listing.
Read-only by default; opt-in write mode adds create/update/delete for test cases and category/category-matcher management.
allure-testops-mcp
An MCP server for Allure TestOps. It lets an LLM agent (Claude Code, Cursor, OpenCode, …) explore and manage projects, launches, test cases, test results and reference data through the Allure REST API.
Stack: Python 3.10+, FastMCP, stdio transport.
Compatibility: any Allure TestOps instance — SaaS
qameta.ioor self-hosted / on-prem (API at/api/rs).Instance-wide — all projects at once: one connection serves every project on the instance. The server isn't pinned to a single project — discover them with
allure_list_projects, then pass anyproject_id. No reconfiguration to switch or compare projects.Corporate-friendly: API-token auth, optional SSL-verify toggle, deliberate proxy bypass.
Safe by default: 13 read-only tools; the 7 write tools are off unless you opt in.
Quick start
claude mcp add allure -s user \
--env ALLURE_URL=https://allure.example.com \
--env ALLURE_TOKEN=your-api-token \
-- uvx --from allure-testops-mcp allure-testops-mcpThen ask your agent: "List all Allure projects" or "Show failed tests in the last launch for project 175". Get an API token in Allure TestOps under Profile → API tokens. See Configuration for other clients and Environment variables for all options.
Related MCP server: Allure TestOps MCP
Tools at a glance
20 tools — 13 read-only (always on) and 7 write tools (opt-in via ALLURE_ENABLE_WRITE=true). Every tool
carries MCP annotations and returns both a typed structuredContent payload and a markdown summary.
Tool | Kind | Purpose |
| read | All projects (id, name, abbreviation) |
| read | TC count, automation rate, last-launch summary |
| read | Recent launches with pass/fail stats |
| read | Test results in a launch (filter by status) |
| read | FAILED/BROKEN tests in the last or a given launch |
| read | Test cases (automated/manual + owner filters) |
| read | One test case's full detail + scenario steps |
| read | A test case's custom-field values |
| read | A project's statuses (id, name, color) |
| read | A project's test layers (id, name) |
| read | A project's custom-field schema |
| read | Defect categories (named/coloured buckets) |
| read | Regex automation rules (message/trace → category) |
| write ⚑ | Create a test case |
| write ⚑ | Partial update of a test case |
| write ⚑ | Permanent delete (destructive — needs |
| write ⚑ | Create a defect category |
| write ⚑ | Permanent delete (destructive — needs |
| write ⚑ | Create + attach a regex automation rule |
| write ⚑ | Permanent delete (destructive — needs |
⚑ Registered only when ALLURE_ENABLE_WRITE=true. Without the flag they are never imported, so the agent
never sees them — see Security considerations.
Write tools — status & layer by name or id
allure_create_test_case / allure_update_test_case accept status and layer as either a name
(status / layer) or a numeric id (status_id / layer_id). Names are auto-resolved to ids against
the project's status/layer lists (GET /api/rs/status, GET /api/rs/testlayer) — an unknown name returns an
actionable error listing the valid options. Update is partial (only the fields you pass change), and
allure_delete_test_case is irreversible: it carries destructiveHint: True (compliant clients prompt) and
additionally requires an explicit confirm=true argument.
Design highlights
Full tool annotations — read tools are
readOnlyHint: True/openWorldHint: Trueso clients don't prompt;allure_delete_test_caseisdestructiveHint: True.Structured output on every tool — each tool declares a
TypedDictreturn type, so FastMCP auto-generates anoutputSchemaand every result carries bothstructuredContentand a markdown block.Actionable errors — auth / 400 / 403 / 404 / 409 / 429 / 5xx / missing-env errors are converted to specific, next-step messages (e.g. "Authentication failed — verify ALLURE_TOKEN has API scope").
Pydantic input validation — every argument has typed constraints (ranges, lengths, literals), exposed as JSON Schema; usernames are alphabet-restricted to prevent RQL injection.
Pagination — list tools return a
paginationblock withpage,total,has_more,next_page.Progress reporting — multi-call tools emit
ctx.report_progress+ctx.infoevents.Version-agnostic update verb —
allure_update_test_caseissuesPATCHand falls back toPUTon HTTP 405, so it works across Allure deployments that expose only one verb.Single source of truth for version —
__version__derives from installed package metadata, and a test assertspyproject.tomlmatches bothserver.jsonversion fields, so the published version can't drift.
Installation
Requires Python 3.10+. No manual install needed if you use uvx (recommended) — your MCP client runs it.
# run on demand via uvx (recommended)
uvx --from allure-testops-mcp allure-testops-mcp
# or install with pipx
pipx install allure-testops-mcpConfiguration
Claude Code — one command:
claude mcp add allure -s user \
--env ALLURE_URL=https://allure.example.com \
--env ALLURE_TOKEN=your-api-token \
--env ALLURE_SSL_VERIFY=true \
-- uvx --from allure-testops-mcp allure-testops-mcpAny MCP client — add to ~/.claude.json, a project .mcp.json, Cursor's mcp.json, etc.:
{
"mcpServers": {
"allure": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "allure-testops-mcp", "allure-testops-mcp"],
"env": {
"ALLURE_URL": "https://allure.example.com",
"ALLURE_TOKEN": "${ALLURE_TOKEN}",
"ALLURE_SSL_VERIFY": "true"
}
}
}
}See .env.example for a template. Verify the connection:
claude mcp list
# allure: uvx --from allure-testops-mcp allure-testops-mcp - ✓ ConnectedEnvironment variables
Variable | Required | Default | Description |
| yes | — | Allure TestOps URL (e.g. |
| yes | — | API token (Allure → Profile → API tokens) |
| no |
|
|
| no |
|
|
ALLURE_TEST_PROJECT_ID (plus optional ALLURE_TEST_STATUS / ALLURE_TEST_LAYER) are used only by the
opt-in live integration tests — see Development.
Updating
The server is a stdio process your client respawns each session, so the running version is decided by the
uvx invocation. uvx caches the resolved environment under ~/.cache/uv, so an older version sticks until
you refresh:
uvx --refresh --from allure-testops-mcp allure-testops-mcp # force latest on next run
uv cache clean allure-testops-mcp # or drop the cached envThen reconnect the server (/mcp → reconnect, or restart the session). To control the version from config,
edit args — pin for stability, or always-latest for currency:
// Pin a version (deterministic; bump consciously)
"args": ["--from", "allure-testops-mcp==0.8.0", "allure-testops-mcp"]
// Always latest on every start (adds a PyPI lookup per launch)
"args": ["--refresh", "--from", "allure-testops-mcp", "allure-testops-mcp"]Example prompts
Read-only:
"List all Allure projects"
"Show the last 10 launches for project 63"
"Failed tests in the last launch for project 175"
"What's the automation rate for project 842?"
"Compare the automation rate of project 63 and project 842" — works across projects in one session
"Show me the steps of test case 641012"
"Which custom fields does project 1664 have?"
With ALLURE_ENABLE_WRITE=true, drive test-case CRUD in natural language:
"Create a Draft manual TC named 'Login flow' in project 63"
"Add an automated smoke TC in project 63 tagged
smoke, layerE2E""Rename test case 555 to 'Login (rewritten)' and set its status to Active"
"Delete test case 555" — the agent passes
confirm=true, and a compliant client prompts you first
Security considerations
API token is read from
ALLURE_TOKENonly — never passed on the command line, never written to logs.Secrets are never echoed back in tool responses (no header dumps, no auth reflection).
Self-signed SSL is opt-in via
ALLURE_SSL_VERIFY=false(defaulttrue). Disabling verification on a public network is a risk; use only for trusted corporate instances.Proxy discovery is disabled (
session.trust_env = False) — the server ignoresHTTP_PROXY/HTTPS_PROXYso it can't be silently routed through an unintended proxy.Writes are opt-in and least-privilege — without
ALLURE_ENABLE_WRITE=truethe server registers only the 13 read-only tools and cannot create, modify, or delete anything, even with a write-scoped token. When enabled, the destructive tools (allure_delete_test_case/allure_delete_category/allure_delete_category_matcher) carrydestructiveHint: Trueand requireconfirm=true.Input validation via Pydantic — every argument is typed and bounded; usernames are alphabet-restricted to prevent RQL injection through the search endpoint.
A token is never more privileged than its account — Allure
Api-Tokenauth inherits the issuing user's role, so a read-only (guest) account yields a read-only server regardless of theALLURE_ENABLE_WRITEflag.
Rate limits
Allure TestOps enforces per-instance rate limits (typically ~60 requests/minute per token). On HTTP 429 the
server returns an actionable error suggesting you wait 30–60s, reduce size, or paginate with smaller pages.
Two tools make multiple API calls internally — allure_get_project_statistics (3) and
allure_search_failed_tests (2–3) — and report per-step progress via MCP Context.
Development
git clone https://github.com/mshegolev/allure-testops-mcp.git
cd allure-testops-mcp
pip install -e '.[dev]'
pytest # unit suite (all HTTP mocked)
ruff check src tests && ruff format --check src testsRun the server directly (stdio transport — waits on stdin for MCP messages):
ALLURE_URL=... ALLURE_TOKEN=... allure-testops-mcpLive-instance integration tests
An opt-in suite runs a real create → update → delete lifecycle against a live Allure project. It is
deselected by default and skips itself unless credentials are present, so a normal pytest stays green:
export ALLURE_URL=https://allure.example.com
export ALLURE_TOKEN=... # token from an account with write access
export ALLURE_ENABLE_WRITE=true
export ALLURE_TEST_PROJECT_ID=63 # a throwaway project you can write to
pytest -m integration tests/integration -vContributing
Issues and PRs welcome. Keep the unit suite green (pytest) and the linter clean (ruff check,
ruff format); CI runs both on Python 3.10 / 3.11 / 3.12. See CHANGELOG.md for the
release history.
License
MIT © Mikhail Shchegolev
Available Tools
11 toolsallure_get_project_statisticsARead-onlyIdempotent
Get summary statistics for an Allure project.
Returns TC count, automation rate, and the last closed launch's pass/fail breakdown. Performs 3-4 API calls — progress is reported via MCP Context (visible as progress updates in compatible clients).
Args:
project_id: Allure project ID (see allure_list_projects).
ctx: MCP Context injected by FastMCP (used for progress reporting;
never supplied by the agent directly).
Returns:
dict with keys:
- project_id (int)
- total_test_cases (int)
- automated_test_cases (int)
- manual_test_cases (int)
- automation_rate_pct (float)
- last_launch_id (int | None): latest closed launch
- last_launch_name (str | None)
- last_launch_passed / last_launch_failed / last_launch_broken (int)
- last_launch_total (int)
- recent_launches_count (int): launches examined to find the latest closed one
Examples:
- "How automated is project 63?" -> project_id=63, read automation_rate_pct
- "What was the last passing run for project 175?" -> read last_launch_passed
Don't use when:
- You need per-test detail (use ``allure_get_test_results``).
- You need the full launch history (use ``allure_list_launches``).
Inputs: project_id (required). Returns: project_id, total_test_cases, automated_test_cases, manual_test_cases, +8 more
allure_get_test_caseARead-onlyIdempotent
Get one test case's full detail — fields, status/layer, tags, and steps.
Unlike allure_list_test_cases (summaries), this returns the body of a
single test case: description, precondition, expected result, and the
manual scenario steps (flattened with a depth marker). Use it to read
or review the actual content of a test case.
Returns:
dict with id, name, project_id, automated,
description, precondition, expected_result, status,
layer, tags and steps (each: depth, keyword,
name, expected_result). steps is empty when
include_scenario is false or the case has none.
Inputs: test_case_id (required), include_scenario. Returns: id, name, project_id, automated, +9 more
allure_get_test_case_custom_fieldsARead-onlyIdempotent
List the custom-field values set on a test case.
Returns each value flattened to field_id / field_name (the custom
field) and value_id / value_name (the chosen value) — e.g. field
"Priority" → value "High". These are not included in
allure_get_test_case; fetch them here when you need a test case's
custom-field assignments.
Inputs: test_case_id (required). Returns: test_case_id, count, custom_fields
allure_get_test_resultsARead-onlyIdempotent
Get individual test results inside a launch, optionally filtered by status.
Args:
launch_id: Allure launch ID (from allure_list_launches).
status: Filter — PASSED / FAILED / BROKEN / SKIPPED. None returns all.
page: 0-based page index.
size: Items per page (1-200; default 50).
Returns:
dict with keys:
- launch_id (int)
- count (int)
- pagination (dict)
- results (list): each with id / name / status /
duration_ms / error (first 300 chars of statusMessage)
Examples:
- "FAILED tests in launch 12345" -> launch_id=12345, status="FAILED"
- "All results in launch X, second page" -> launch_id=X, page=1
Don't use when:
- You want only FAILED+BROKEN (``allure_search_failed_tests`` does both in one call).
Inputs: launch_id (required), status, page, size. Returns: launch_id, count, pagination, results
allure_list_custom_fieldsARead-onlyIdempotent
List the custom fields defined on a project (its schema).
Returns each field's field_id, name, single_select and
required. Use it to discover which custom fields a project has before
reading a test case's values with allure_get_test_case_custom_fields.
Built-in metadata fields (Epic/Feature/Story/Component/Suite) use negative
ids; project-specific custom fields use positive ids.
Inputs: project_id (required). Returns: project_id, count, custom_fields
allure_list_launchesARead-onlyIdempotent
List recent launches for a project, newest first.
Each launch carries a pass/fail/broken/skipped breakdown from Allure's
statistic field. Pagination info is returned in the pagination
block (use next_page to continue).
Args: project_id: Allure project ID. page: 0-based page index. size: Items per page (1-100; 20 is usually enough for triage).
Returns:
dict with keys:
- project_id (int)
- count (int): items in this response
- pagination (dict): page / size / total /
total_pages / has_more / next_page
- launches (list): each with id / name / status /
created_date / passed / failed / broken /
skipped / total
Examples:
- "Last 10 launches for project 63" -> project_id=63, size=10
- "Older launches beyond page 1" -> repeat with page=1
Don't use when:
- You need test results inside a launch (``allure_get_test_results``).
- You need just the latest FAILED/BROKEN tests (``allure_search_failed_tests``).
Inputs: project_id (required), page, size. Returns: project_id, count, pagination, launches
allure_list_layersARead-onlyIdempotent
List the test layers defined in a project (id, name).
Use this to discover valid layer names/ids before setting a layer on
allure_create_test_case / allure_update_test_case. Built-in
layers use negative ids (e.g. API Tests = -3).
Returns:
dict with project_id, count and layers (each: id, name).
Inputs: project_id (required). Returns: project_id, count, layers
allure_list_projectsARead-onlyIdempotent
List all projects in the Allure TestOps instance.
Use this first to discover which project IDs exist — all other tools
take a project_id that you can look up here.
Returns:
dict with keys:
- count (int): number of projects in this response
- projects (list): each item has id, name, abbreviation
Examples:
- "Which projects exist in Allure?" -> default call, take the names/ids
- "Find project by abbreviation" -> iterate projects and match
Don't use when:
- You already know the project id (skip discovery, go straight to the target tool).
Inputs: page, size. Returns: count, projects
allure_list_statusesARead-onlyIdempotent
List the test-case statuses defined in a project (id, name, color).
Use this to discover valid status names/ids before setting a status on
allure_create_test_case / allure_update_test_case. Built-in
statuses use negative ids (e.g. Draft = -1).
Returns:
dict with project_id, count and statuses (each: id,
name, color).
Inputs: project_id (required). Returns: project_id, count, statuses
allure_list_test_casesARead-onlyIdempotent
List test cases for a project with optional automation and ownership filters.
Each TC carries id, name, automated, status, layer
(e.g. UNIT, API, E2E), the createdBy / lastModifiedBy
audit usernames, and a flat list of tag names. Caveat: the audit
fields and tags are only populated when owner is set, because
Allure's plain /testcase endpoint returns a compact projection
that omits them — the owner path uses __search which returns
the full projection.
Args:
project_id: Allure project ID.
ctx: MCP Context (auto-injected by FastMCP for progress reporting).
automated: True — only automated, False — only manual,
None — both.
owner: Optional Allure username. When set, the response is narrowed
to TCs where createdBy = owner OR lastModifiedBy = owner
(case-sensitive, exact match), enforced server-side via
Allure's RQL __search endpoint. The username must match
[A-Za-z0-9._@-]+ — anything else is rejected at the MCP
input layer (Pydantic pattern) to prevent RQL injection.
**Why "creator/modifier" and not "owner".** Allure TestOps does
not expose a separate ``owner`` field in RQL on most
deployments — the closest stable proxy for "TCs I touched" is
the union of ``createdBy`` and ``lastModifiedBy``.
**Trade-off when ``owner`` is set.** ``__search`` does not
accept the ``automated`` query parameter, so an ``automated``
filter combined with ``owner`` is applied **client-side after
the page is fetched**. ``pagination`` then reflects the raw
owner-filtered set, not the further automation-filtered view —
a fetched page of 50 may shrink. Raise ``size`` (max 200) or
iterate ``page`` for full coverage.
page: 0-based page index.
size: Items per page (1-200; default 50).Returns:
dict with keys:
- project_id (int)
- count (int): items in this response (post any client-side automated filter)
- pagination (dict): raw Allure paging
- test_cases (list): each item carries id / name /
automated / status / layer / created_by /
last_modified_by / tags
Examples:
- "How many manual TCs does project 63 have?" -> project_id=63, automated=False, read pagination.total
- "First 200 automated TCs" -> automated=True, size=200
- "My manual TCs in project 63" -> project_id=63, automated=False, owner="jdoe", size=200
Don't use when:
- You need just the automation % (``allure_get_project_statistics``).
Inputs: project_id (required), automated, owner, page, +1 more. Returns: project_id, count, pagination, test_cases
allure_search_failed_testsARead-onlyIdempotent
Find FAILED and BROKEN tests in the most recent (or given) launch.
Useful for triage: "what's broken in the latest run" without listing every test. Performs up to 3 API calls; progress reported via MCP Context.
Args:
project_id: Allure project ID.
launch_id: Specific launch ID. If None, the latest launch is used.
limit: Max failures per status (so up to 2 * limit total).
ctx: MCP Context (auto-injected).
Returns:
dict with keys:
- launch_id (int): the resolved launch (latest if not passed in)
- failed_count (int)
- results (list): id / name / status / duration_ms / error
Examples:
- "What's failing in project 63 right now?" -> project_id=63
- "Failures in launch 98765" -> project_id=N, launch_id=98765
Don't use when:
- You need PASSED tests too (use ``allure_get_test_results`` without status filter).
Inputs: project_id (required), launch_id, limit. Returns: launch_id, failed_count, results, reason
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct entity or operation (projects, statistics, test cases, launches, results, failures, custom fields, layers, statuses) with clear boundaries and explicit 'Don't use when' guidance to prevent misselection.
All tools follow a consistent 'allure_verb_noun' pattern (e.g., allure_list_projects, allure_get_test_case), making the naming predictable and easy to navigate.
With 11 tools, the set is well-scoped for a test management server, covering essential query and list operations without being overwhelming.
The tools are heavily read-focused, missing create/update/delete operations for test cases and other entities, which are fundamental to full lifecycle management. The descriptions reference 'allure_create_test_case' but it is not included.
Maintenance
Related MCP Connectors
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Run, debug, and triage tests from your IDE using natural language, no dashboard switching, no manual data transfers. The TestMu AI (formerly LambdaTest) MCP Server is a single remote server exposing four tool suites: HyperExecute — analyze your project, generate YAML configs and test runner commands, then monitor jobs and sessions. Automation — pull a TestID's details plus command, network, and console logs into one chat for instant root-cause analysis. Includes mobile app upload. SmartUI — explain pixel, layout, DOM, and perceptual changes in a visual regression run, with context-aware React/HTML/CSS fixes. Accessibility — audit any public URL or a local React app against WCAG and get ready-to-apply remediation steps. Connects over https://mcp.lambdatest.com/mcp using OAuth 2.1 — no API keys in your config. One-click install in Cursor; works with Claude, GitHub Copilot, Cline, and any MCP client. Tests execute on the TestMu AI cloud: 3,000+ browsers and 10,000+ real devices.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseBqualityAmaintenanceAI-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 strongly-typed tool schemas and per-project custom field validation that helps LLMs generate valid TestRail requests on the first try.271,151 npm45Apache 2.0
- AlicenseCqualityCmaintenanceProduction-ready MCP server for Allure TestOps, enabling test case, launch, test result, and test plan management via natural language.100297 npm2MIT
- AlicenseBqualityBmaintenanceAn MCP server for Allure TestOps that enables AI agents to manage test cases, defects, test plans, and other test management entities with clear, easy-to-use tools and helpful error guidance.70408 PyPI8Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that connects AI agents to TestOps, enabling test case management, launches, defects, and analytics through natural language.48MIT