Lucius MCP

Allure TestOps MCP Server

Lucius is a specialized Model Context Protocol (MCP) server for Allure TestOps, built with FastMCP and Starlette.

🎯 Motivation

Allure TestOps is a powerful tool with a huge API. When you're using an AI agent to manage your tests, it can easily get lost in the details or fail because of a small technical mistake.

Lucius makes this easier by giving your AI tools that are simple to use and hard to break:

• Clear Tools: Every tool is designed for a specific task, like "finding a test case" or "updating a launch".
• Helpful Errors: If an AI makes a mistake, Lucius doesn't just return a code—it provides an "Agent Hint" that explains exactly what went wrong and how to fix it.
• Solid Foundation: We follow a clean "Thin Tool" structure, meaning the logic is consistent and easy for both humans and AI to follow.

🛠️ Supported Tools

See the full reference in Tool Reference.

Tool Category	Description	All Tools
Test Case Mgmt	Full lifecycle for test documentation.	create_test_case, update_test_case, delete_test_case, delete_archived_test_cases, get_test_case_details, get_test_case_custom_fields
Automation Generation	Generate framework-specific code from existing test cases.	generate_test_code
Search & Discovery	Advanced search and project metadata discovery.	list_test_cases, search_test_cases, get_custom_fields, list_integrations, get_project
Shared Steps	Create and manage reusable step sequences.	create_shared_step, list_shared_steps, update_shared_step, delete_shared_step, delete_archived_shared_steps, link_shared_step, unlink_shared_step
Test Layers	Manage test taxonomy and auto-mapping schemas.	list_test_layers, create_test_layer, update_test_layer, delete_test_layer, list_test_layer_schemas, create_test_layer_schema, update_test_layer_schema, delete_test_layer_schema
Test Hierarchy	Organize suites and assign tests in tree paths.	create_test_suite, list_test_suites, assign_test_cases_to_suite, delete_test_suite
Custom Fields	Project-level management of custom field values.	list_custom_field_values, create_custom_field_value, update_custom_field_value, delete_custom_field_value, delete_unused_custom_fields
Launch Management	Manage launches, result uploads, manual execution, reruns, and attachments.	create_launch, list_launches, get_launch, list_launch_test_results, upload_test_results, attach_file_to_launch, rerun_test_results_manually, start_manual_test_session, submit_manual_test_results, add_test_result_attachment
Test Result Management	Inspect one exact TestOps result and prepare verified evidence downloads.	get_test_result, prepare_attachment_download
Test Plans	Manage test plans and their content.	create_test_plan, update_test_plan, delete_test_plan, list_test_plans, manage_test_plan_content, run_test_plan
Defect Mgmt	Track defects, linkage, and automation rules.	create_defect, get_defect, update_defect, delete_defect, list_defects, link_defect_to_test_case, unlink_issue_from_test_case, list_defect_test_cases, create_defect_matcher, list_defect_matchers, update_defect_matcher, delete_defect_matcher

🚀 Quick Start

1. Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
2. Setup Credentials: Create a .env file with the variables below, or save CLI auth with lucius auth.
3. Run Server: uv run start

Basic .env for Quick Start

Variable	Description	Example
ALLURE_ENDPOINT	Allure TestOps base URL	https://example.testops.cloud
ALLURE_PROJECT_ID	Default Allure project ID (optional for get_project; required by project-scoped tools)	123
ALLURE_API_TOKEN	Allure API token	<your_api_token>
MCP_MODE	MCP transport mode for Lucius runtime	stdio

🔌 Claude Desktop Integration

The easiest way to use Lucius in Claude Desktop is via the .mcpb bundle:

1. Download the latest lucius-mcp.mcpb from Releases.
2. Open with Claude Desktop.
3. Configure your Allure credentials in the UI.

💻 Claude Code Integration

To add Lucius to Claude Code, use the following command from within your project directory:

claude mcp add --transport stdio --scope project \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  testops-mcp -- uvx --from lucius-mcp --refresh start

Project-scoped text config example (.mcp.json):

{
  "mcpServers": {
    "testops-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "lucius-mcp",
        "--refresh",
        "start"
      ],
      "env": {
        "ALLURE_ENDPOINT": "https://example.testops.cloud",
        "ALLURE_PROJECT_ID": "123",
        "ALLURE_API_TOKEN": "<your_api_token>",
        "MCP_MODE": "stdio"
      }
    }
  }
}

🧠 Codex Integration

To add Lucius to Codex (CLI or IDE extension), use:

codex mcp add testops-mcp \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  -- uvx --from lucius-mcp --refresh start

Text config example (~/.codex/config.toml or project .codex/config.toml):

[mcp_servers.testops-mcp]
command = "uvx"
args = ["--from", "lucius-mcp", "--refresh", "start"]

[mcp_servers.testops-mcp.env]
ALLURE_ENDPOINT = "https://example.testops.cloud"
ALLURE_PROJECT_ID = "123"
ALLURE_API_TOKEN = "<your_api_token>"
MCP_MODE = "stdio"

For detailed setup, including Claude Desktop (MCPB) integration, see Setup Guide.

🐍 Supported Python versions

Lucius supports Python 3.10 through 3.14 for runtime use. The generated MCPB manifests and the representative Nuitka CLI compiler matrix validate the same range. Python 3.15 support is experimental: installation may require source builds, and platform compatibility is still being verified. See the development guide for current limitations. Python 3.9 remains unsupported because the pinned Starlette requirement needs Python 3.10 or newer.

💻 Command-Line Interface (CLI)

Lucius also provides a universal CLI entry point for direct tool execution from the command line:

# List available actions for an entity
uv run lucius test_case

# Execute an action
uv run lucius test_case get --args '{"test_case_id": 1234}'

# Show help for a specific entity/action
uv run lucius test_case get --help

# Save reusable CLI auth
uv run lucius auth --url https://example.testops.cloud --token <your_api_token> --project 123
uv run lucius auth status
uv run lucius auth clear

CLI Features:

• 🎯 Type-safe entity/action invocation with validation
• 🔐 Optional persistent CLI auth with native per-user config storage
• 📊 Multiple output formats (JSON, table, csv, plain)
• 🔍 Per-action help with parameters and examples
• 🛡️ Clean error messages with guidance
• 📦 Standalone binaries for Linux, macOS, and Windows

CLI auth precedence is:

1. Explicit tool args such as api_token or project_id
2. Environment variables
3. Saved CLI auth config from uv run lucius auth
4. Defaults

Saved CLI auth uses native config locations:

• Linux/Unix: $XDG_CONFIG_HOME/lucius/auth.json or ~/.config/lucius/auth.json
• macOS: ~/Library/Application Support/lucius/auth.json unless XDG overrides are explicitly set
• Windows: %LOCALAPPDATA%\lucius\auth.json

For full CLI documentation and installation instructions, see CLI Guide.

📡 Telemetry

Lucius collects privacy-preserving usage telemetry to improve tool quality. Telemetry is enabled by default and sends metadata to https://stats.ostanin.me, an endpoint operated by the project owner (no third party has access to this endpoint).

If this is acceptable in your environment, staying opted in helps improve Lucius over time. If you want to opt out, set TELEMETRY_ENABLED=false in your environment.

No API tokens, test content, or tool arguments are sent.

See Telemetry & Privacy for the full data dictionary and telemetry behavior details.

📂 Documentation

Full documentation is available in the docs/ folder:

• Architecture & Design
• Tool Reference
• Configuration & Setup
• Telemetry & Privacy
• Attachment download capability links
• Development Guide
• AI Agent Protocol

🤝 Contributing

Contributions are welcome! Please see the Contribution Guidelines and the Development Guide for more details.