XRAY Code Intelligence MCP server for AI agents

XRAY is a powerful code intelligence tool for AI assistants that enables them to understand, navigate, and analyze codebases. By providing structure-aware code navigation capabilities, XRAY helps AI assistants move beyond simple text searches to understand symbol relationships and code dependencies.

Installation Options

Option 1: Automated Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/srijanshukla18/xray/main/install.sh | bash

Option 2: Install with uv

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install XRAY
git clone https://github.com/srijanshukla18/xray.git
cd xray
uv tool install .

Option 3: Try with uvx (Without Installation)

# Clone the repository
git clone https://github.com/srijanshukla18/xray.git
cd xray

# Run XRAY directly with uvx
uvx --from . xray-mcp

Configuring Your AI Assistant

Generate Configuration

Use the provided configuration generator script:

# Generate config for your specific tool
python mcp-config-generator.py cursor local_python
python mcp-config-generator.py claude docker  
python mcp-config-generator.py vscode source

Claude CLI Configuration

claude mcp add xray xray-mcp -s local
claude mcp list | grep xray

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "xray": {
      "command": "xray-mcp"
    }
  }
}

Cursor Configuration

Settings → Cursor Settings → MCP → Add new global MCP server:

{
  "mcpServers": {
    "xray": {
      "command": "xray-mcp"
    }
  }
}

Using XRAY

XRAY provides three main tools that follow a progressive discovery workflow:

1. Map - Explore Repository Structure

# Get directory structure overview
tree = explore_repo("/path/to/project")

# Zoom into specific directories with symbol details
tree = explore_repo("/path/to/project", focus_dirs=["src"], include_symbols=True)

# Limit depth for large codebases
tree = explore_repo("/path/to/project", max_depth=2, include_symbols=True)

2. Find - Locate Specific Symbols

# Find symbols matching "authenticate" (fuzzy search)
symbols = find_symbol("/path/to/project", "authenticate")
# Returns list of exact symbol objects with name, type, path, line numbers

3. Impact - Analyze Dependencies

# Find where a symbol is used
symbol = symbols[0]  # From find_symbol
result = what_breaks(symbol)
# Returns information about references to the symbol

Example Prompts

Use XRAY by adding "use XRAY tools" to your prompts:

"Index the src/ directory for analysis. use XRAY tools"

"Find all classes that contain 'User' in their name. use XRAY tools"

"What breaks if I change the authenticate method in UserService? use XRAY tools"

"What does the PaymentProcessor class depend on? use XRAY tools"

Supported Languages

XRAY uses ast-grep for structural code analysis and supports:

Python - Functions, classes, methods, async functions
JavaScript - Functions, classes, arrow functions, imports
TypeScript - All JavaScript features plus interfaces, type aliases
Go - Functions, structs, interfaces, methods

Troubleshooting

Check Installation

# If installed as tool
xray-mcp --version

# If using uvx
uvx --from /path/to/xray xray-mcp --version

Common Issues

uv not found: Add export PATH="$HOME/.cargo/bin:$PATH" to your shell profile
Permission denied: Run chmod +x ~/.local/bin/xray-mcp
Python version issues: XRAY requires Python 3.10+. Check with python --version
MCP connection issues: Run xray-mcp --test and verify your configuration

Advanced Configuration

# Custom database location
export XRAY_DB_PATH="$HOME/.xray/databases"

# Enable debug logging
export XRAY_DEBUG=1

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "xray" '{"command":"xray-mcp"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "xray": {
            "command": "xray-mcp"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "xray": {
            "command": "xray-mcp"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect