Zephyr MCP

An MCP server for Zephyr Scale. The current version provides tools for reading test cases and test steps.

Requirements

• Node.js 20.6 or later
• A Zephyr Scale API token
• Codex CLI or Claude Code CLI
• Bash on Linux or macOS
• Git Bash or WSL on Windows

On Windows, use Git Bash when Node.js and the MCP client are installed on Windows. Use WSL only when Node.js and the Codex or Claude Code CLI are also installed inside the same WSL environment.

1. Get the repository

Clone the repository and enter its directory:

git clone <repository-url>
cd zephyr-mcp

The setup scripts resolve the repository from their own location. After the repository has been cloned, the scripts can be launched from any working directory.

2. Create the repository .env

Get a Zephyr Scale API token

1. Sign in to Jira.
2. Open the profile menu in the top-right corner.
3. Select Zephyr Scale API Access Tokens.
4. Create a token, copy it, and store it securely. Do not commit or share it.

Configure .env

Copy .env.example to .env in the root of the cloned zephyr-mcp repository:

cp .env.example .env

Then replace the placeholder token:

ZEPHYR_API_TOKEN=your-zephyr-api-token

# Optional
# ZEPHYR_CUSTOM_BASE_URL=https://api.zephyrscale.smartbear.com/v2

The repository ignores .env files. Do not commit your API token.

The setup scripts store only the path to this file in the MCP configuration. They do not copy the token into Codex or Claude Code configuration files.

3. Run the setup script

No separate dependency installation, build, or manual MCP configuration is required. The selected script handles those steps automatically.

If zephyr-mcp was previously installed globally from a .tgz package, append --global to the setup command to use that package instead of building the repository source.

Codex

From the repository:

bash setup-mcp-codex.sh

From another directory:

bash /absolute/path/to/zephyr-mcp/setup-mcp-codex.sh

The script registers a user-level zephyr MCP server in Codex. If a server with that name already exists, it is replaced.

Restart Codex and verify the connection:

/mcp

Claude Code

From the repository:

bash setup-mcp-claude.sh

From another directory:

bash /absolute/path/to/zephyr-mcp/setup-mcp-claude.sh

The script registers a user-scoped zephyr MCP server in Claude Code. If a server with that name already exists, it is replaced.

Restart Claude Code and verify the connection:

/mcp

You can also inspect the registration from the terminal:

claude mcp get zephyr

What the setup scripts do

Both scripts:

1. Resolve the repository path from the script location.
2. Require Node.js 20.6 or later.
3. Check that .env exists in the repository.
4. Verify that ZEPHYR_API_TOKEN is not empty without printing it.
5. Install missing dependencies and build the local server in default --source mode.
6. Use the globally installed .tgz package when passed --global.
7. Normalize paths when running through Git Bash on Windows.
8. Replace the existing zephyr MCP registration.
9. Configure Node to load the repository .env using --env-file.

Troubleshooting

Missing .env

Error: Missing .../.env. Create it with ZEPHYR_API_TOKEN before running this script.

Create .env next to setup-mcp-codex.sh and setup-mcp-claude.sh.

Missing API token

Error: ZEPHYR_API_TOKEN is missing or empty in .../.env.

Add a non-empty ZEPHYR_API_TOKEN to the repository .env.

MCP startup failure

Run the relevant setup script again:

bash setup-mcp-codex.sh
# or
bash setup-mcp-claude.sh

The script validates .env, rebuilds the server in source mode, and replaces the existing MCP registration. Restart the MCP client and check /mcp after the script completes.

Development

npm run typecheck
npm run build

Source code is located in src/; compiled output is written to build/.