Zephyr Squad MCP Server (FastMCP)

The Zephyr Squad MCP Server is a standalone Model Context Protocol (MCP) server that enables AI-driven management of Zephyr test assets directly from an MCP client (Claude, Devin, Cascade, etc.). It lets you create and manage test cases, test steps, test cycles, and Jira associations using natural language — eliminating manual CSV imports and repetitive clicking through Jira and Zephyr UIs.

It integrates with Jira and Zephyr while maintaining enterprise-grade security through system environment variable / Azure Key Vault authentication and existing Jira authorization controls.

Business Problem

Organizations spend significant time creating and managing test assets across the software development lifecycle. Developers, QA engineers, and product teams often need to create test cases, document test steps, link tests to Jira stories, and organize them into test cycles. These activities are typically performed manually through the Jira and Zephyr UIs, making the process repetitive, time-consuming, and prone to inconsistencies — especially during sprint planning, feature delivery, and release testing.

To address this, this standalone MCP server lets an AI assistant interact directly with Jira and Zephyr through natural language. Instead of navigating multiple screens and manually entering data, you describe what you want in plain English and the assistant performs the required actions.

Typical activities covered:

• Creating test cases

• Defining test steps

• Linking tests to Jira requirements

• Organizing tests into execution cycles

• Maintaining traceability between stories and tests

Related MCP server: JIRA Zephyr MCP Server

Why Not the Official Atlassian MCP Server?

Conclusion: The official Atlassian MCP server is structurally incompatible with this setup — both because of on-premise hosting and because Zephyr is outside its scope. Hence, this custom MCP server.

Architecture

┌─────────────────────┐
│   MCP Client          │  (Claude Desktop / Cascade / Devin, etc.)
└──────────┬───────────┘
           │ MCP tool calls (stdio or streamable-http)
┌──────────▼───────────┐
│ zephyr_mcp_server.py  │  FastMCP server — exposes every operation
│                       │  as an @mcp.tool(), does logging
└──────────┬───────────┘
           │ plain function calls
┌──────────▼───────────┐
│ zephyr_client.py      │  The ONLY place that makes HTTP calls.
│                       │  Wraps Jira REST API v2 + Zephyr REST API.
│                       │  Handles auth, retries, caching.
└──────────┬───────────┘
           │ HTTPS + Bearer token
┌──────────▼───────────┐
│  Jira / Zephyr        │  Self-hosted Jira instance + Zephyr plugin
└───────────────────────┘

• zephyr_client.py — HTTP client. Wraps the Jira Core REST API v2 (issue CRUD, search, linking) and the Zephyr test-management REST API (test cases, steps, cycles, executions). Handles session pooling, retry/backoff on 5xx errors, and result caching (permanent ID caches + TTL caches for volatile data).

• zephyr_mcp_server.py — Thin FastMCP wrapper. Every public function in zephyr_client.py is exposed as an MCP tool with a docstring the AI client uses to decide when/how to call it. Also handles structured logging to zephyr_mcp.log.

Available Tools

Setup

1. Install dependencies

pip install -r requirements.txt

2. Configure credentials

Create a config.toml in the project root:

[jira]
base_url = "https://jira.yourcompany.net"
username = "your-jira-username"

[azure]
key_vault_url = "https://your-vault.vault.azure.net"

[defaults]
test_reviewer = "your-jira-username"
folder = "/Regression"
app_mnemonic = "MYAPP"
test_type = "Regression Test"
automation_status = "To Be Automated"

Or use environment variables instead (JIRA_BASE_URL, JIRA_USERNAME, JIRA_TOKEN, AZURE_KEY_VAULT_URL).

Authentication: the Jira Personal Access Token is read from Azure Key Vault (secret name JIRA-TOKEN) if key_vault_url is configured, falling back to the JIRA_TOKEN environment variable. Requires az login once on your machine for DefaultAzureCredential to work. base_url must be HTTPS — plain HTTP is rejected to avoid sending the bearer token unencrypted.

3. Register the MCP server

Copy claude_desktop_config.json to %APPDATA%\Claude\claude_desktop_config.json (Windows) or the equivalent config path for your MCP client, replacing <PATH_OF_YOUR_PROJECT> with the absolute path to this project folder. Restart the client and check its MCP server settings to confirm it connected.

4. Run standalone (optional)

python zephyr_mcp_server.py            # stdio transport (default, for MCP clients)
python zephyr_mcp_server.py --http     # streamable-http transport on port 8000

Security Notes

• No hardcoded credentials — token resolution goes Key Vault → env var → explicit failure on a placeholder token.

• HTTPS enforced for base_url.

• Shared requests.Session with automatic retry/backoff on 500/502/503/504.

• Destructive operations (delete_test_case) require an explicit, non-empty issue key and are logged.

Known Issues / TODO

• get_execution_results / get_cycle_execution_summary signature currently doesn't match between the client and server layers — needs alignment on whether cycles are scoped by cycle_key alone or by (cycle_id, project_key, version_id).

• No automated test suite yet — coverage and audit logic in zephyr_client.py would benefit most from unit tests.

• Confirm requirements.txt version floors stay pinned to what's actually available in your environment's package index.

License

Internal tool — no license specified.