sulu-mcp 1.0.0

MCP server exposing Sulu TMS to LLM agents (read + triage)

Sulu MCP server

An MCP server that lets an LLM agent observe and triage a Sulu TMS instance. It is a thin client over Sulu's existing REST API — no backend changes required. It runs locally over stdio.

What it exposes

37 tools (read + triage + authoring + ingest), all acting as the user who owns the API token:

• Observe: check_connection, list_projects, get_project, project_glance, top_failing_tests, list_test_cases, get_test_case, get_test_case_markdown (agent-facing Markdown scenario for executing the case), search_test_cases, list_launches, get_launch, list_launch_results, get_test_result, list_launch_defects, list_tags, list_defects, get_defect, get_folder_tree, list_test_plans, get_test_plan.
• Author / organize (write): create_test_case, update_test_case (steps, precondition, expected result, parameters, tag ids, folder), create_tag, create_folder, move_test_case_to_folder, create_test_plan, set_test_plan_cases.
• Triage (write): set_test_result_status, assign_results, create_defect, close_defect, reopen_defect, link_defect_results, link_defect_cases.
• Execute (write): create_launch (seeds selected cases), finish_launch.
• Ingest (write): upload_test_report — upload an allure-results dir / JUnit XML / ZIP as a new launch.

Install

The package is published on PyPI as sulu-mcp. With uv installed, no explicit install step is needed — uvx sulu-mcp fetches and runs it.

Mint a token in Sulu: Profile → API tokens (it is shown in plaintext once).

Configuration

Env var	Required	Default	Meaning
SULU_API_TOKEN	yes	—	Personal API token (Bearer). The agent acts as this user.
SULU_BASE_URL	no	http://localhost:8080	Sulu base URL (no trailing /api) — https://app.aisulu.dev for SaaS, or your on-premise instance URL.
SULU_PROJECT_ID	no	—	Default project for upload_test_report when the call omits project_id.

Register in Claude Code

The server name comes first, then the -e env flags, then -- and the launch command. -e/--env is variadic — placed before the name it swallows sulu as a value (Invalid environment variable format: sulu):

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

Register in Claude Desktop

Add to its mcpServers config:

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

From source (this repo)

cd mcp
uv sync
cp .env.example .env   # then set SULU_API_TOKEN
SULU_API_TOKEN=<token> uv run sulu-mcp

To register a from-source checkout instead of the PyPI package, replace uvx sulu-mcp with uv --directory /absolute/path/to/sulu/mcp run sulu-mcp in the commands above.

Test

cd mcp && uv run pytest

Scope

stdio only; single user (env token); read + triage + authoring + ingest. Authoring of test-case scenarios is done via update_test_case (the create endpoint takes metadata only). Out of scope: running automated tests on CI (no thin REST path — use a CI Job in the web UI), custom-field values, folder rename/move/delete, tag update/delete, defect↔Jira, deletes/bulk-destructive ops, schema mutation, remote/HTTP transport, multi-user auth.

License

Apache-2.0 — the full text ships in the package's LICENSE file. The Sulu product itself is licensed separately.