Zephyr Squad MCP Server
Enables AI-driven management of Zephyr test assets within Jira, including creating test cases, test plans, and test steps, linking tests to Jira issues, retrieving test coverage and execution summaries, and searching Jira issues.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Zephyr-Jira MCP + AI Agent Layer
A standalone, self-hosted Model Context Protocol (MCP) project with two layers:
Atomic tool server (
zephyr_mcp_server.py) — exposes Jira and Zephyr Scale test-management operations as MCP tools an AI assistant (Claude, Cursor, Windsurf, Devin, or any MCP-compatible client) can call directly: create test cases, link them to stories, audit test cycles, generate coverage reports.AI agent layer (
zephyr_agent_server.py+zephyr_agent.py) — an independent MCP server and CLI that hand whole multi-step workflows to an LLM-driven agent ("generate test cases for this story, add steps, link them, and report") using your own provider — Anthropic, OpenAI, Azure OpenAI, or any OpenAI-compatible internal gateway.
Background
Organizations spend significant time creating and managing test assets across the software development lifecycle. Developers, QA engineers, and product teams routinely 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, which makes the process repetitive, time-consuming, and prone to inconsistency — especially during sprint planning, feature delivery, and release testing.
To address this, this project 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. The atomic tool server covers single operations; the agent layer goes further and orchestrates entire workflows — plan → create → link → audit → report — in one instruction.
Related MCP server: JIRA Zephyr MCP Server
Problem Statement
There are now hundreds of community and vendor MCP servers available for Jira, Zephyr, and other QA/test-management tools. In practice, almost none of them are usable inside a bank, insurer, or other regulated enterprise environment, because they typically:
Route data through a third-party proxy or SaaS backend that the security team has no visibility into or control over.
Risk data leakage — test data, defect descriptions, and Jira issue content routinely contain confidential project, customer, or infrastructure details that cannot leave the corporate network.
Require broad, unscoped credentials (personal API tokens pasted into config files, no secret rotation, no audit trail).
Fail enterprise security review outright, because the vendor cannot show where the server runs, where the token is stored, or what egress the tool makes.
Why Not the Official Atlassian MCP Server?
Reason | Detail |
Cloud-only |
|
Private/on-premise blocked | Our Jira instance, |
No Zephyr support | Even on Cloud, the Atlassian MCP covers only native Jira/Confluence APIs. Zephyr is a third-party plugin with its own separate REST API that isn't exposed by the Atlassian MCP. |
No Zephyr API access | The Atlassian MCP has no knowledge of Zephyr's test case, test step, test cycle, or execution endpoints. |
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 project.
Design Principles
Standalone, self-hosted. Both servers run entirely inside your own network (or your own machine) as local processes. There is no external SaaS component, no vendor cloud, and no data ever leaves your environment unless your own Jira instance — or your own chosen LLM endpoint — is reached.
Your Jira, your rules. The Jira base URL is a configuration value you set yourself, e.g.
https://jira.yourcompany.net— the server talks directly to your Jira/Zephyr instance over your existing network path (VPN, internal DNS, corporate proxy — whatever your organization already enforces). No requests go anywhere else.Your LLM, your rules. The agent layer is provider-agnostic: one
[llm]block inconfig.tomlpoints it at Anthropic, OpenAI, Azure OpenAI, or an internal OpenAI-compatible gateway (LiteLLM, vLLM, Ollama). Choose an internal endpoint and LLM traffic stays inside the same boundary as Jira traffic.No secrets in code or config files. API tokens are never hardcoded and never committed. They resolve at runtime from Azure Key Vault, or from environment variables / a gitignored
.envfile (see.env.example), so credential storage and rotation stay owned by your existing secrets-management infrastructure.Least-surface footprint. The servers only implement the operations they explicitly expose as tools — there is no generic proxy, no arbitrary API pass-through, and no catch-all "run any REST call" tool. Mutating agent actions are approval-gated, and
delete_test_caseis hidden unless explicitly enabled.Transparent and auditable. Every tool call is logged locally (
zephyr_mcp.log,zephyr_agent.log) with the acting user, action, and target issue/project — giving you a local audit trail independent of Jira's own logs.Fail loud at startup.
validate_config()runs when either server or the CLI boots — a missing base URL, non-HTTPS Jira, or missing/placeholder token exits immediately instead of failing mid-task.
What It Does
The tool server wraps zephyr_client.py (a thin client over the Jira and Zephyr Scale REST APIs) and exposes each operation as an MCP tool. The agent server then orchestrates those tools with an LLM for multi-step work. Once connected to an MCP client, an assistant can:
Category | Tools |
Resolution | Resolve project keys, issue keys, and issue types to their underlying Jira IDs |
Test case management | Create, bulk-create, list, and delete Zephyr test cases; discover custom field IDs per project |
Test design | Read and write test steps in Step-by-Step, BDD/Gherkin, or plain-text format |
Linking & collaboration | Link tests to stories/bugs/epics; add comments to any Jira issue |
Test cycles & execution | Fetch test cycles, execution results, and per-cycle pass/fail summaries; audit a cycle for missing attachments or unresolved statuses |
Coverage & reporting | Report test coverage against stories/bugs in a project or sprint; generate aggregate pass/fail summaries |
Jira queries | Fetch any issue by key; run arbitrary JQL searches |
The agent layer adds workflow-level operations on top: run_workflow, cover_story, audit_sprint, release_report, list_workflows — plus the run_agent() function and zephyr_agent.py CLI for free-form instructions.
Architecture
flowchart TD
A["MCP Client<br/>Claude Desktop, coding agents, etc."]
F["CLI / run_agent()<br/>zephyr_agent.py"]
G["zephyr_agent_server.py<br/>FastMCP — workflow-level tools"]
B["zephyr_mcp_server.py<br/>FastMCP — atomic tool definitions, logging"]
C["zephyr_client.py<br/>Jira + Zephyr Scale REST client"]
D["Your Jira Instance<br/>jira.yourcompany.net"]
E["Azure Key Vault / .env<br/>secrets resolved at runtime"]
L["Your LLM Endpoint<br/>Anthropic / OpenAI / Azure / gateway"]
A -->|stdio / streamable-http| B
A -->|stdio / streamable-http| G
G -->|run_agent| F
F -->|in-process tool calls| B
F <-->|tool-call loop| L
B --> C
C -->|REST API + JIRA_TOKEN| D
E -->|Runtime secrets| C
E -->|Runtime secrets| L
style A fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
style F fill:#fdf3e3,stroke:#e8710a,stroke-width:2px
style G fill:#fdf3e3,stroke:#e8710a,stroke-width:2px
style B fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
style C fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
style D fill:#e6f4ea,stroke:#188038,stroke-width:2px
style E fill:#fff4e5,stroke:#f29900,stroke-width:2px
style L fill:#f3e8fd,stroke:#9334e6,stroke-width:2pxPrerequisites
Python 3.10+
Access to a Jira instance with Zephyr Scale (ATM) enabled
An Azure Key Vault instance holding your Jira API token as a secret named
JIRA-TOKEN, with the identity running this server grantedget/listaccess to that secretAn MCP-compatible client (e.g. Claude Desktop)
(Agent layer only) an LLM endpoint — Anthropic/OpenAI/Azure OpenAI or an internal gateway — with its API key in Key Vault (e.g.
ANTHROPIC-API-KEY); see AGENT_LAYER.md
Setup
Clone and install dependencies
git clone https://github.com/VenkateshDoijode/custom-mcp.git cd custom-mcp pip install -r requirements.txtConfigure
config.tomlwith your Jira details (and LLM settings if you want the agent layer)[jira] base_url = "https://jira.yourcompany.net" username = "your-jira-username" [azure] key_vault_url = "https://your-keyvault-name.vault.azure.net/" [llm] # agent layer only — see AGENT_LAYER.md §3–4 provider = "anthropic" # or openai | azure_openai | openai_compatible model = "claude-sonnet-4-5"Provide secrets — either grant Key Vault access to the identity running the server (managed identity, service principal, or
az login), scoped to readJIRA-TOKENonly; or copy.env.exampleto.envand fill in values (never commit.env). Environment variables always take precedence.Register the server(s) with your MCP client — see
claude_desktop_config.jsonfor a working example, and point it at the absolute path ofzephyr_mcp_server.py(atomic tools) and/orzephyr_agent_server.py(workflow agent).Run it
python zephyr_mcp_server.py # atomic tools — stdio for MCP clients python zephyr_mcp_server.py --http # streamable-http on port 8000 python zephyr_agent_server.py # agent layer — stdio for MCP clients python zephyr_agent.py "instruction" # agent CLI — no MCP client needed
Use with Any Coding Agent
Each server works completely independently. Register one, the other, or both — they are separate FastMCP servers with no shared runtime state:
Server | Exposes | Use it for |
| ~20 atomic Jira/Zephyr tools | Fine-grained control — "create one test case", "comment on PG1-123" |
| 5 workflow-level tools ( | Multi-step jobs — "cover this story end-to-end", "audit the sprint" |
Any MCP-compatible client — Claude Desktop, Cursor, Windsurf, Devin, VS Code MCP, or a custom agent — registers them the same way, as stdio processes:
{
"mcpServers": {
"zephyr-tools": {
"command": "python",
"args": ["/absolute/path/to/custom-mcp/zephyr_mcp_server.py"]
},
"zephyr-agent": {
"command": "python",
"args": ["/absolute/path/to/custom-mcp/zephyr_agent_server.py"]
}
}
}Claude Desktop →
claude_desktop_config.json(working example in this repo)Cursor / Windsurf →
~/.cursor/mcp.json/~/.codeium/windsurf/mcp_config.json— samemcpServersshapeHTTP clients → start either server with
--httpand point the client athttp://localhost:8000/mcpNo MCP client at all →
python zephyr_agent.py "instruction"runs the agent layer directly from the shell
Each server validates config and credentials at startup — a bad setup exits with a clear error in the client's log instead of failing mid-conversation.
Security Posture
Concern | How it's handled here |
Credential storage | Jira token pulled from Azure Key Vault at runtime, or from env vars / a gitignored |
Startup validation |
|
Network exposure | Server runs locally/on-prem; only outbound calls are to your own Jira base URL |
Data residency | No third-party proxy or SaaS relay — test and issue data never leaves your network boundary |
Least privilege | Tools are scoped to specific Jira/Zephyr operations, not a general-purpose API proxy |
Auditability | All tool invocations are logged with the acting user, action, and target key |
Destructive actions | Operations like |
This is a personal/team project, not an officially reviewed enterprise product. Before deploying it in a regulated environment, run it through your organization's standard security and architecture review — the design choices above are meant to make that review straightforward, not to replace it.
AI Agent Layer
The atomic tools above are now wrapped by an agent layer: hand over a whole workflow in one instruction — "Generate test cases for this new story, link them, and audit last sprint's execution cycle for gaps." — and the agent chains resolution → creation → linking → reporting itself.
Independent second MCP server (
zephyr_agent_server.py) — register it in any MCP-compatible coding agent alongside or instead of the atomic server.Provider-agnostic — Anthropic, OpenAI, Azure OpenAI, or any OpenAI-compatible gateway (LiteLLM, vLLM, Ollama, internal). One
[llm]block inconfig.tomlselects provider/model/endpoint/auth; keys resolve from Azure Key Vault like the Jira token.CLI (
zephyr_agent.py) — free-form instructions plus predefined workflows (cover_story,audit_sprint,release_report), with--dry-run, approval prompts, and a destructive-tool gate.Same audit trail — the agent orchestrates the atomic tools in-process, so every action is still logged in
zephyr_mcp.log.
python zephyr_agent.py --workflow cover_story --arg issue_key=PG1-123
python zephyr_agent_server.py # stdio — register in your MCP clientFull setup, provider configs, and guardrails: AGENT_LAYER.md — complete run/start runbook: RUN_AGENT.md.
Agent mode sends Jira issue/story content to the configured LLM endpoint — choose
azure_openaior an internalopenai_compatiblegateway to keep that traffic inside your network boundary, and review it under the same security process as the rest of this project.
Repository Contents
File | Purpose |
| FastMCP server — registers all atomic tools, handles logging and transport |
| Jira + Zephyr Scale REST client — the only module that makes Jira HTTP calls |
| Independent MCP server exposing the AI agent layer (workflow-level tools) |
| Agent engine ( |
| OPTIONAL FastAPI browser chat UI over the same engine ( |
| Provider-agnostic LLM adapters (Anthropic / OpenAI / Azure OpenAI / gateways) |
| End-to-end agent layer documentation |
| Detailed runbook — how to run/start the agent (CLI, MCP, API, cron) |
| What MCP and FastMCP are, and how this project layers them |
| Captured real dry-run — guardrails and tabular output in action |
| Documented env-var / |
| Example MCP client configuration |
| Python dependencies (tail has optional UI deps, safe to skip) |
Author
Venkateshwara Doijode — Test Automation Lead
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Test management for AI agents: cases, runs, results, cycles and traceability.
Run browser journeys on the app you build with AI, and manage test cases, launches and defects.
Direct access to Cypress tests results and accessibility reports in your AI workflow.
Related MCP Servers
- AlicenseBqualityBmaintenanceIntegrates with Zebrunner Test Case Management to help QA teams manage test cases, test suites, and test execution data through AI assistants. Features intelligent validation, automated test code generation, and comprehensive reporting capabilities.4994 npm5AGPL 3.0
- AlicenseAqualityDmaintenanceEnables comprehensive test management with JIRA's Zephyr system, allowing users to create and manage test plans, execute test cycles, track progress, and generate reports through natural language.1311MIT
- FlicenseNot gradedqualityDmaintenanceEnables comprehensive test management through SmartBear Zephyr Scale's REST API, supporting automated workflows for test cases, cycles, executions, folders, and linking tests to Jira issues through natural language.3-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Zephyr Scale Cloud for test management, including test cases, cycles, plans, folders, priorities, and statuses via the MCP protocol.3MIT