mcp-xray

A lightweight server that bridges the MCP protocol with the Atlassian Jira Xray API. It loads an OpenAPI spec for Xray and exposes it via FastMCP, supporting multiple transports and simple configuration.

Rationale

This project provides a simple way to interact with the Xray API using FastMCP, making it easier to develop and test applications that integrate with Jira Xray. This server is primarily intended for use with Xray Server+DC configuration.

For Xray Cloud it’s recommended to use GraphQL API + mcp-graphql integration. It provides a more efficient and flexible way to interact with Xray Cloud, leveraging the capabilities of GraphQL.

Here is a Clarification on Xray APIs usage for Xray Server+DC or Xray Cloud: Xray API Usage Clarification.

Features

• FastMCP server for Jira Xray API
• Personal Access Token authentication
• OpenAPI spec loading from file
• Multiple transports: stdio, SSE, streamable HTTP
• Read-only mode for safe, non-destructive API access
• Simple CLI and environment variable configuration

Requirements

• Python 3.12+
• uv (recommended for fast installs)
• Xray API Personal Access Token
• OpenAPI spec file for Xray

Installation

Using uvx (recommended)

The easiest way to run mcp-xray is using uvx:

uvx mcp-xray --help

Using pip

pip install mcp-xray

From source

git clone https://github.com/tivaliy/mcp-xray.git
cd mcp-xray
uv sync
uv run mcp-xray --help

Quick Start Guide

1. Obtain a Personal Access Token (PAT) for Xray

   • Log in to your Jira instance with Xray installed.
   • Go to your user profile or Xray settings.
   • Find the section for API tokens or Personal Access Tokens.
   • Generate a new token and copy it. (See Xray documentation for details.)

2. Get the Xray OpenAPI spec

   • The OpenAPI (Swagger) spec for the relevant Xray version can be provided as either a local file path or a direct URL.
   • The spec may be downloaded from an Xray server, obtained from the official documentation, or referenced via a direct URL if available.
   • Only json format is supported for now.

3. Configure and run in VS Code

   • Open the project in VS Code.
   • Use the provided below example settings to configure the server.
   • When you start the server via the VS Code MCP extension or command palette, you will be prompted for your Xray API token securely.
   • Example configuration using PyPI release (see .vscode/mcp.json.example):

     {
         "inputs": [
             {
                 "type": "promptString",