Content
# mcp-xray
A lightweight server that bridges the [MCP](https://modelcontextprotocol.io/introduction) 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](https://docs.getxray.app/display/XRAYCLOUD/GraphQL+API) + [mcp-graphql](https://github.com/blurrah/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](https://docs.getxray.app/display/XRAY/Clarifications+on+APIs+usage).
## 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](https://github.com/astral-sh/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](https://docs.astral.sh/uv/guides/tools/):
```bash
uvx mcp-xray --help
```
### Using pip
```bash
pip install mcp-xray
```
### From source
```bash
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](https://docs.getxray.app/display/XRAY/REST+API) for details.)
1. **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.
1. **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`):
```json
{
"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:
```bash
# 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](https://gofastmcp.com/integrations/openapi#route-mapping)
- [Component Names documentation](https://gofastmcp.com/integrations/openapi#component-names)
- 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](https://github.com/Xray-App/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](LICENSE) file for details
