mcp-xray

mcp-xray is a lightweight MCP server that bridges the MCP protocol with the Jira Xray REST API. It loads an OpenAPI spec for Xray and exposes the endpoints over FastMCP, supporting multiple transports such as stdio, SSE, and HTTP streaming. The server can be run in read-only mode to safely explore and test Xray endpoints without performing writes. To use it, provide a valid Xray Personal Access Token and point the server at your Xray OpenAPI spec (local file or URL). The configuration exposes a ready-to-use interface tailored for Xray Server+DC configurations, with guidance for token handling and OpenAPI spec usage. You’ll authenticate via a token, and the server will map OpenAPI paths to FastMCP routes so you can interact with Xray resources through MCP tooling and transports.

Tools and capabilities include:

• Read-only mode to prevent destructive operations while testing integrations.
• Support for multiple transports (stdio, server-sent events, and streamable HTTP) to fit your environment.
• OpenAPI-based mapping, loading xray_v2.0.json to expose Xray REST endpoints.
• Simple CLI and environment-variable configuration to supply the Xray URL and authentication token at runtime.

Typical workflows involve supplying your Xray URL, the required openapi spec file, and a token, then starting the server with uvx mcp-xray and using MCP-compatible clients to invoke Xray operations. The setup is designed for rapid testing and development with Jira Xray in both Server+DC configurations and, where applicable, Cloud scenarios via recommended GraphQL approaches.

Prerequisites:

• Python 3.12+ (recommended via uvx)
• uv (Astral uv) installed
• Access to a Jira Xray server and a valid Personal Access Token (PAT)
• An OpenAPI spec file for Xray (e.g., xray_v2.0.json) either locally or accessible via URL

Installation steps:

1. Install uvx and the mcp-xray package (via uvx) or install from source:

   • Using uvx (recommended): uvx mcp-xray --help

2. If installing from source: git clone https://github.com/tivaliy/mcp-xray.git cd mcp-xray uv sync uv run mcp-xray --help

3. Prepare configuration:

   • Ensure you have an OpenAPI spec file (xray_v2.0.json) available locally or accessible by URL.
   • Create a config.yaml if using specific route mappings or read-only behavior (optional).

4. Run the server:

   • Example command (adjust environment variables and paths as needed): uvx mcp-xray
     --xray-url https://your-domain.example.com/jira/rest/raven/2.0/api
     --xray-openapi-spec xray_v2.0.json
     --xray-personal-token $XRAY_TOKEN
     --config-file config.yaml
     --read-only

5. Verify startup:

   • Check console output for readiness and available routes.
   • If you’re behind a firewall or proxy, ensure outbound access to the Xray API endpoint is allowed.

Tips and caveats:

• The server requires an Xray Personal Access Token; the token is typically provided at runtime and may be prompted or supplied via environment variables depending on your setup.
• The OpenAPI spec (xray_v2.0.json) is a manually curated and evolving resource in this project. If endpoints change, you may need to update the spec accordingly.
• When using read-only mode, write operations (POST, PUT, DELETE) are blocked. If both route_maps and read-only are configured, route_maps takes precedence for permitted methods.
• Transport options (stdio, SSE, streamable HTTP) enable flexible integration patterns; choose the transport that best fits your environment (e.g., local development vs. remote integration).
• If you need to customize endpoint mappings or component names, refer to the OpenAPI route-mapping and component-name guidance included in the project documentation.
• For Xray Cloud, consider exploring GraphQL API approaches in combination with mcp-graphql as an alternative integration path.