lucius

Lucius is a specialized MCP (Model Context Protocol) server built to interface with Allure TestOps. It exposes a curated set of tools for test case management, search and discovery, shared steps, test layers, test hierarchy, custom fields, test plans, and defect management. Each tool is designed to perform a specific task (for example creating or updating a test case, or linking a defect to a test case) and provides actionable agent hints when errors occur, helping AI agents interact with Allure TestOps reliably. The server is built with a thin tool approach, ensuring consistent logic that AI agents can follow across the various workflows.

To use Lucius, deploy the MCP server via uvx (Python/uv) and point your client or Claude integration to the Lucius package. The Claude integration examples show how to add Lucius in stdio mode and how to pass Allure credentials. Once running, you can invoke the available tools such as create_test_case, update_test_case, search_test_cases, list_test_layers, create_test_plan, and more, depending on your needs. The server returns structured results and, when something goes wrong, provides an Agent Hint with guidance on what to fix.

Prerequisites:

• Python with uv installed (the uv tool or uvx driver)
• Network access to Allure TestOps API
• Access credentials for Allure (endpoint, project ID, API token)

Step-by-step installation:

1. Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install the Lucius MCP package (via uvx):

# Install using the package name defined for Lucius MCP
uvx install lucius-mcp

3. Prepare environment variables (example):

# Create a .env file or export variables in your environment
export ALLURE_ENDPOINT=https://your-allure-endpoint
export ALLURE_PROJECT_ID=your-project-id
export ALLURE_API_TOKEN=your-api-token
export MCP_MODE=stdio

4. Run the server:

uv run start

5. Verify the server is running by hitting the expected MCP endpoint or using the client/Claude integration command:

# Example trigger to ensure the server responds (adjust as needed)
# This will depend on your client; refer to the docs for exact invocation

Notes:

• Ensure your Allure credentials have the necessary permissions for the operations you intend to perform.
• If you run into SSL or network issues, confirm that the endpoint URL is correct and reachable from your deployment environment.

Tips and common considerations:

• The MCP_MODE is set to stdio for Claude Code integration; adjust as needed for different transports.
• Always validate your Allure Project ID and API token before starting the server to avoid authentication errors.
• If you encounter tool-specific errors, refer to the Agent Hint provided by Lucius to understand the corrective steps.
• Keep the Lucius MCP package up to date to benefit from new tools and improvements in the toolset.
• For debugging, enable verbose logs if available in your uvx configuration to capture tool calls and responses.