MCP server

Connect AI agents to Sulu with the official MCP server. Published on PyPI as sulu-mcp, it runs locally on your machine and talks to Sulu through the same REST API you use — the agent acts as you, with your permissions.

What agents can do

The server exposes 37 tools covering the day-to-day TMS workflow:

• Observe — browse projects, test cases, launches, results, defects, tags, folders, and test plans; pull a per-project health summary and top failing tests.
• Author — create and update test cases (steps, preconditions, parameters, tags, folders), create tags, folders, and test plans.
• Triage — set result statuses, assign results, create/close/reopen defects, and link defects to results and cases.
• Execute & ingest — create and finish launches, and upload test reports (allure-results, JUnit XML, or a ZIP) as a new launch.

Prerequisites

• uv installed — the uvx command fetches and runs sulu-mcp on demand, no manual install step.
• A Sulu API token: in Sulu, open Profile → API tokens and mint one. The token is shown in plaintext once — store it in your secrets manager.

Configuration

The server is configured entirely through environment variables:

Variable	Required	Meaning
SULU_API_TOKEN	yes	Your personal API token. Every tool call runs with this user's permissions.
SULU_BASE_URL	no	Sulu base URL, without a trailing /api — https://app.aisulu.dev for Sulu Cloud, or your self-hosted instance URL. Defaults to http://localhost:8080.
SULU_PROJECT_ID	no	Default project for report uploads when the call doesn't specify one.

Register in Claude Code

claude mcp add sulu \
  -e SULU_API_TOKEN=<token> -e SULU_BASE_URL=https://app.aisulu.dev \
  -- uvx sulu-mcp

Then ask Claude to, for example, "list the failed results in the latest launch and draft defects for the new failures".

Register in Claude Desktop

Add the server to the mcpServers section of the Claude Desktop configuration:

{
  "mcpServers": {
    "sulu": {
      "command": "uvx",
      "args": ["sulu-mcp"],
      "env": {
        "SULU_API_TOKEN": "<token>",
        "SULU_BASE_URL": "https://app.aisulu.dev"
      }
    }
  }
}

Any other MCP-capable client works the same way: command uvx, argument sulu-mcp, plus the two environment variables.

Scope and limitations

• Transport is stdio only — the server runs locally next to your MCP client; nothing extra is deployed on the Sulu side.
• Single user per registration: all actions are performed as the token's owner and are subject to that user's project permissions.
• Destructive operations (deletes, bulk-destructive actions) are deliberately not exposed.

For uploading reports from CI rather than from an agent, see Import test reports.