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",
                 "id": "xray_token",
                 "description": "Xray Personal Access Token",
                 "password": true
             }
         ],
         "servers": {
             "mcp-xray": {
                 "command": "uvx",
                 "args": [
                     "mcp-xray",
                     "--xray-url",
                     "https://your-domain.example.com/jira/rest/raven/2.0/api",
                     "--xray-personal-token",
                     "${input:xray_token}",
                     "--xray-openapi-spec",
                     "xray_v2.0.json",
                     "--config-file",
                     "config.yaml",
                     "--read-only"
                 ]
             }
         }
     }
     

   • Alternatively, to use a specific version or install from git:

     # Specific version
     uvx mcp-xray@0.1.0 --help
     
     # From git (latest main branch)
     uvx --from git+https://github.com/tivaliy/mcp-xray@main mcp-xray --help
     

   • Adjust the --xray-url, --xray-openapi-spec, and --config-file as needed for the environment.
   • The --xray-openapi-spec option accepts either a local file path or a URL.
   • The optional --config-file parameter must point to the configuration file (see config.yaml as an example).
   • For details on route mapping and component naming in OpenAPI integrations, see:
     • Route Mapping documentation
     • Component Names documentation
   • The optional --read-only flag starts the server in read-only mode, blocking all write operations (POST, PUT, DELETE) for safe, non-destructive access.
     • Note: If both --read-only and route_maps are set in the config file, route_maps takes precedence and customizes the allowed/disallowed methods.
   • The Xray personal access token will be prompted interactively and not stored in plain text.

OpenAPI Schema: Source, Limitations, and Maintenance

The xray_v2.0.json file in this repository provides an OpenAPI 3.0 specification for the Xray Server/DC REST API v2.0.

• The official Xray API documentation is distributed across multiple versions (v1 and v2), and there is no single, complete OpenAPI file provided by Xray.
• This file was generated by exporting endpoints from the official Xray Postman collections and then manually adjusted to fit OpenAPI 3.0 standards and project needs.
• Some endpoints, schemas, or details may be incomplete or require further validation. The file is a best-effort representation and may need updates as the Xray API evolves or as new requirements arise.
• If you need to update or extend the OpenAPI spec, you will likely need to manually "compile" a new version by merging information from the Postman collections, official docs, and your own testing.
• Contributions and corrections are welcome. Please validate any changes to ensure compatibility with the actual Xray API.

Summary:

The OpenAPI schema in this repo is a manually curated and evolving resource. It is not an official, complete export from Xray, but a practical tool for integration and automation. Treat it as a living document that may require future validation and manual updates.

License

This project is licensed under the MIT License. See the LICENSE file for details