# Mcp Jira Xray

> MCP server for Jira Xray integration - Extract test cases, executions, and project data for AI-powered test automation workflows

- **Type:** MCP server
- **Install:** `agentstack add mcp-sajithrw-mcp-jira-xray`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sajithrw](https://agentstack.voostack.com/s/sajithrw)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sajithrw](https://github.com/sajithrw)
- **Source:** https://github.com/sajithrw/mcp-jira-xray

## Install

```sh
agentstack add mcp-sajithrw-mcp-jira-xray
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Jira Xray Server

A Model Context Protocol (MCP) server for extracting test information from Jira Xray. This server connects to Jira instances with Xray Test Management and extracts test cases related to specific tickets.

## Features

- 🔍 Extract tests related to any Jira ticket
- 📋 List test executions linked to tickets
- 🎨 Configurable JSON output format
- 💾 Automatic saving to the `extractions` folder
- 🔐 Secure connection using Jira API tokens

## Installation

### Prerequisites

- Node.js 17 or higher
- A Jira instance with Xray Test Management
- Jira API token

### Setup

1. Clone this repository or install via npm:

```bash
git clone 
cd mcp-jira-xray
npm install
```

2. **Run the interactive setup:**

```bash
npm run setup
```

This will guide you through:
- Entering your Jira host URL
- Providing your Jira email
- Adding your API token
- Validating the connection
- Configuring output format

**Or** manually create a `.env` file:

```bash
cp .env.example .env
# Edit .env with your credentials
```

### Getting a Jira API Token

1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Give it a label and copy the token
4. Use this token in your `.env` file

## Configuration

### Jira Connection

The server requires three configuration values:

- `JIRA_HOST`: Your Jira instance URL (e.g., `https://mycompany.atlassian.net`)
- `JIRA_EMAIL`: Your Jira account email
- `JIRA_API_TOKEN`: Your Jira API token

### Output Format

The `OUTPUT_FORMAT` environment variable defines the JSON structure for extracted test data. You can customize this to match your needs.

**Default format:**
```json
{
  "ticketId": "",
  "test": "",
  "testCases": []
}
```

**Custom format example:**
```json
{
  "ticket": {
    "id": "",
    "name": ""
  },
  "tests": {
    "cases": []
  }
}
```

The server will populate the fields based on these keys:
- `ticketId` → The Jira ticket ID
- `test` → The ticket summary
- `testCases` → Array of test case descriptions

## Usage

### With VS Code

**Good news!** The server is already configured for this project in `.vscode/mcp.json`. 

**Quick Start:**
1. Make sure you've run `npm run setup` (configuration complete)
2. Open Command Palette: `Cmd/Ctrl + Shift + P`
3. Type: "MCP: Enable" and press Enter
4. Try: "Extract tests for ticket PROJ-123" in Copilot Chat

📖 **See [VSCODE-SETUP.md](./VSCODE-SETUP.md) for complete VS Code installation guide**

### With Claude Desktop

Add this to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jira-xray": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-xray/build/index.js"]
    }
  }
}
```

### Available Tools

#### 1. `extract_tests`
Extracts all tests related to a given Jira ticket.

**Parameters:**
- `ticketId` (string): The Jira ticket ID (e.g., "PROJ-123")

**Example:**
```
Extract tests for ticket PROJ-123
```

**Output:**
- Test execution details
- All test cases with descriptions
- Saved to `extractions/PROJ-123_.json`

#### 2. `list_test_executions`
Lists all test executions linked to a Jira ticket.

**Parameters:**
- `ticketId` (string): The Jira ticket ID

**Example:**
```
List test executions for PROJ-123
```

**Output:**
- List of test execution keys
- Test execution summaries
- Execution statuses

## Output Files

All extracted test data is saved to the `extractions/` folder with the following naming convention:

```
extractions/_.json
```

Example: `extractions/PROJ-123_2024-01-15T10-30-45-123Z.json`

## Development

### Interactive Setup

Run the setup wizard:

```bash
npm run setup
```

### Validate Configuration

Test your Jira connection:

```bash
npm run validate
```

This will:
- Check your .env configuration
- Test connection to Jira
- Verify authentication
- List accessible projects
- Confirm permissions

### Build

```bash
npm run build
```

This compiles TypeScript to JavaScript in the `build/` directory.

### Project Structure

```
mcp-jira-xray/
├── src/
│   ├── index.ts           # Main MCP server entry point
│   ├── jira-client.ts     # Jira API client
│   ├── config.ts          # Configuration management
│   └── output-handler.ts  # File output handling
├── build/                 # Compiled JavaScript (generated)
├── extractions/           # Output files (generated)
├── .env                   # Environment configuration
├── .env.example           # Example configuration
├── package.json
├── tsconfig.json
└── README.md
```

## Troubleshooting

### "Missing required environment variables"

Make sure your `.env` file exists and contains all required variables (`JIRA_HOST`, `JIRA_EMAIL`, `JIRA_API_TOKEN`).

### "Failed to get ticket"

- Verify your Jira credentials are correct
- Check that the ticket ID exists in your Jira instance
- Ensure your API token has appropriate permissions

### "Xray API not available"

The server tries multiple methods to extract test data. If Xray-specific APIs aren't available, it falls back to standard Jira JQL queries. This may happen if:
- Xray is not installed on your Jira instance
- Your account doesn't have Xray permissions

### Connection Issues

- Ensure your `JIRA_HOST` includes the protocol (https://)
- Check that your network allows connections to Jira
- Verify your API token is valid and not expired

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## Support

For issues and questions:
- Check existing [GitHub Issues](/issues)
- Create a new issue with detailed information
- Include your Jira and Xray versions

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sajithrw](https://github.com/sajithrw)
- **Source:** [sajithrw/mcp-jira-xray](https://github.com/sajithrw/mcp-jira-xray)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sajithrw-mcp-jira-xray
- Seller: https://agentstack.voostack.com/s/sajithrw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.