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

Test Runs

Note: assign_test_cases, add_test_run_results, and create_test_run_from_suite require a backend endpoint not yet available. They will be enabled in a future release.

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"

"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"

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: 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