tambora-mcp

MCP server that exposes Tambora test case management operations as native tools for Claude. Allows Claude to create test cases, manage test runs, and list existing tests without generating and executing scripts manually.

Requirements

• Python 3.10+
• A running Tambora instance with API access
• Claude Code (claude.ai/code) or any MCP-compatible client

Installation

Option A — No install, via uvx (recommended)

If you have uv installed, you don't need to install anything up front — point your MCP client at uvx tambora-mcp@latest (see MCP Setup below). The @latest suffix matters: without it, uvx resolves the version once and reuses that cached environment on later runs instead of re-checking PyPI.

Option B — Persistent install from PyPI

pip install tambora-mcp

To install a specific version:

pip install tambora-mcp==0.6.0

Option C — Local development (contributors/maintainers)

git clone https://github.com/koombea/tambora-mcp.git
cd tambora-mcp
pip install -e .

Verify installation

tambora-mcp --help

MCP Setup in Claude Code

1. Locate or create your .mcp.json

The .mcp.json file lives at the root of your project (project-level) or at ~/.claude/mcp.json (global).

2. Add the tambora server

Recommended — no install step, via uvx:

{
  "mcpServers": {
    "tambora": {
      "command": "uvx",
      "args": ["tambora-mcp@latest"],
      "env": {
        "TAMBORA_API_KEY": "your-api-key"
      }
    }
  }
}

Alternative — if you already did a persistent pip install tambora-mcp:

{
  "mcpServers": {
    "tambora": {
      "command": "tambora-mcp",
      "env": {
        "TAMBORA_API_KEY": "your-api-key"
      }
    }
  }
}

3. Restart Claude Code

After saving .mcp.json, restart Claude Code so it picks up the new MCP server. You can verify it loaded correctly by asking Claude:

"Check connectivity to Tambora"

Available MCP Tools

Every tool below except check_connectivity requires a project_key argument (the project's abbreviation, e.g. "KAN", from check_connectivity's projects list).

Test Cases

Suites

The suite tree can be arbitrarily deep (not just a flat module → suite pair). When a module/suite name given to create_test_case/create_test_cases/edit_test_case already exists elsewhere in the project's tree at a different position, the call is rejected instead of silently creating a duplicate/orphan node — pass suite_id/suite_path to target a nested suite unambiguously.

Test Runs

Documents

Docspace is a separate folder/document tree per project, independent of the suite/test-case tree. Document content is Markdown (converted to/from ProseMirror JSON server-side). Unlike every other tool, only list_documents/create_document take project_key — every other document tool takes a node_id (folder or document UUID) and resolves the project from it directly.

Usage Examples

Once the MCP server is registered, Claude can interact with Tambora conversationally:

"Check connectivity to Tambora"

"Create a test case for the login flow with Given/When/Then steps under the Authentication module"

"Bulk-create 3 test cases for the Sign Up suite"

"List all test cases in the Authentication module, Login suite"

"Edit TC-MPP-42 and mark it as manual"

"List all suites in the project"

"Create a nested suite called 'Contraseña' under the Mi Cineco suite"

"Delete the empty orphan suite with id d4f18d44-..."

"Add TC-MPP-42 and TC-MPP-43 to the Login suite"

"Create a test run called 'Regression v1.2.0' and mark it as In Progress"

"Complete test run TR-MPP-14"

"Create a folder called 'Specs' in the docspace"

"Create a document called 'Onboarding' with some Markdown content under the Specs folder"

"List the documents in the project and show me the version history of DOC-MPP-1"

End-to-end workflow example

1. Read requirements from a Jira ticket or spec
2. Bulk-create BDD test cases in the appropriate module and suite
3. Add the test cases to the relevant suite with add_test_cases_to_suite
4. Create a Test Run with a descriptive name
5. Complete the Test Run once execution is done

Releasing a New Version (for maintainers)

Versioning is automatic — the package version is derived from the git tag at build time, so there's nothing to bump in source. To cut a release:

git tag v0.6.0
git push origin v0.6.0

Pushing the tag triggers .github/workflows/publish.yml, which builds the package and publishes it to PyPI. Watch the run under the repo's Actions tab, then confirm the new version is live at pypi.org/project/tambora-mcp. Users on uvx tambora-mcp@latest pick up the new version automatically; persistent installs upgrade with pip install --upgrade tambora-mcp.

Architecture

tambora_mcp/
├── server.py     # FastMCP server, tool definitions, env config
├── client.py     # Low-level HTTP client for the Tambora REST API
├── creator.py    # High-level adapter used at test-generation time
└── __main__.py   # Entry point for python -m tambora_mcp

• TamboraClient — handles HTTP, retries, and error handling. POST timeouts abort immediately and do not retry to prevent duplicate creation.
• TamboraCreator — normalizes MCP input fields (gherkin, severity, is_automated) into the API schema (description, priority, automation_status).
• server.py — wires everything together via FastMCP and reads configuration from environment variables at startup.

Changelog

Unreleased

• New tools: list_documents, create_document, retrieve_document, edit_document, delete_document, upload_document_image, list_document_versions, get_document_version, restore_document_version — manage a project's docspace (folder/document) tree, independent from the suite/test-case tree. Document content is Markdown, converted to/from ProseMirror JSON server-side. Unlike other tools, the node_id-based ones don't take project_key — the project is resolved from the node id directly.
• New field: compliance_risk — optional free-text field on create_test_case/create_test_cases/edit_test_case, passed straight through to the backend and included in list_test_cases' response. Unlike the taxonomy fields, passing "" on edit stores a literal empty string rather than clearing it to null.
• Fix: bulk_create_test_cases's fallback to individual creates no longer triggers on a definitive 4xx rejection from the bulk endpoint (only on genuine infra failures — 5xx after retries, connection errors). The bulk endpoint is transactional; falling back there was silently creating the exact partial state (orphan suites + a stray test case) the rejection was meant to prevent.
• Fix: suite placement / "empty suite" bug. create_test_case/create_test_cases/edit_test_case now reject (instead of silently creating a duplicate/orphan node) whenever the given module/suite name already exists elsewhere in the project's suite tree at a different position. Added suite_id/suite_path params to all three tools to target a suite at any depth unambiguously, bypassing name resolution entirely, plus create_missing to control whether a genuinely-missing suite segment gets auto-created or rejected.
• New tools: create_suite (create a single suite anywhere in the tree) and delete_suite (delete an empty orphan suite, optionally cascading over an empty subtree) — for precisely targeting nested suites and cleaning up orphans left behind by earlier ambiguous placement.
• Fix: edit_test_case was sending the wrong wire field names (feature/story instead of module/suite) for its module/suite params, so moving a test case's module/suite via edit silently had no effect.
• New: Jira issue linking. create_test_case/create_test_cases accept an optional linked_issues list of Jira issue keys (e.g. ["TAM-123"]), linked to the test case(s) at creation time. Requires an active Jira integration on the project's organization. list_test_cases gained a jira_key filter, and every returned test case now includes a linked_issues array. Not supported on edit_test_case (backend limitation — that requires the internal Tambora UI/API).
• Required project_key on every tool (except check_connectivity): the backend no longer resolves the project from the API key, since a single key can access multiple projects (see check_connectivity's projects list). Every other call must now pass project_key (the project abbreviation) explicitly. This differs from the TAMBORA_PROJECT_KEY env var tried in v0.3.1 and reverted — project_key is now a required per-call argument, not a static session value.

v0.5.0

• New tool: list_test_run_cases — list all test cases assigned to a test run, filterable by code or name. Each result includes code, summary, description, suite, severity, automation status, and tags.
• New filters for list_test_cases: code (look up a specific test case), created_after, and created_before (ISO 8601 date range filtering).
• Tags on creation: create_test_case now accepts a tags parameter that is sent to the API on creation. No extra edit call required.
• Rename: labels parameter renamed to tags across create_test_case, list_test_cases, creator.py, and client.py for consistency with Tambora's terminology.
• Fix: create_test_case now defaults is_automated to false instead of true.

v0.4.0

• Breaking change: feature/story parameters renamed to module/suite across all tools to match Tambora's hierarchy model (Module → Suite).
• New tools: edit_test_case, list_suites, add_test_cases_to_suite.
• Fix: corrected suite API endpoint paths (/suites/ → /suite/).
• Fix: edit_test_case response now correctly reads the nested data.data envelope from the API.
• Fix: assign_test_cases and add_test_cases_to_suite now accept test_case_codes as a JSON string for reliable MCP client compatibility.

v0.3.1

• Fix: create_test_case and bulk_create_test_cases no longer receive project_key from TamboraCreator.

v0.3.0

• New tool: edit_test_run.
• Fix: corrected test run API endpoint paths (test-runs → testrun).
• Fix: create_test_run now sends status with a default of "Pending".
• Fix: create_test_cases and add_test_run_results now accept list parameters as JSON strings.
• Fix: complete_test_run response now correctly reads the status field.

v0.2.0

• Added list_test_cases, create_test_run, create_test_run_from_suite, assign_test_cases, add_test_run_results, complete_test_run tools.

v0.1.0

• Initial release with check_connectivity, create_test_case, create_test_cases.

License

MIT