youtrack-mcp 0.2.0

YouTrack MCP Server for Model Context Protocol

YouTrack MCP Server

Model Context Protocol (MCP) server for YouTrack integration.

Installation

pip install youtrack-mcp

Usage

Using with uv

"youtrack-mcp": {
    "command": "uv",
    "args": [
        "run",
        "youtrack-mcp"
    ],
    "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "your-token",
        "MCP_SERVER_NAME": "YouTrack MCP Server",
        "MCP_LOG_LEVEL": "INFO"
    }
}

Environment Variables

• YOUTRACK_URL - URL of your YouTrack instance
• YOUTRACK_TOKEN - YouTrack API access token
• MCP_SERVER_NAME - MCP server name
• MCP_LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)

License

MIT

Features

• Issue search
• Detailed issue information
• Update issues (status, assignee, etc.)
• Add comments to issues
• Standardized interface via MCP Python SDK
• Support for stdio and SSE transports
• Integration with Claude Desktop and other MCP-compatible clients

Requirements

• Python 3.10 or higher
• Access to YouTrack with API token
• Installed MCP Python SDK

Development Setup

1. Clone the repository

git clone [repository-url]
cd youtrack_mcp

2. Install dependencies

pip install -r requirements.txt

3. Setup connection to YouTrack

Create a .env file in the root directory of the project with the following variables:

YOUTRACK_URL=https://your-instance.youtrack.cloud
YOUTRACK_TOKEN=your-permanent-token
MCP_SERVER_NAME=YouTrack MCP Server
MCP_LOG_LEVEL=INFO

Or specify these parameters when starting the server via command line arguments.

Running MCP Server

Development and debugging

# Run in development mode with interactive web interface
mcp dev server.py

# With additional dependencies
mcp dev server.py --with pandas --with numpy

Direct run

# Run via MCP module
python server.py

# With additional parameters
python server.py --youtrack-url https://your-instance.youtrack.cloud --youtrack-token your-token --read-only

Command line parameters

• --read-only - Run in read-only mode (blocks write operations)
• --youtrack-url - URL of your YouTrack instance
• --youtrack-token - API token for YouTrack

Integration with Claude Desktop

Step 1: Install server

# Install server in Claude Desktop
mcp install server.py

# With custom name
mcp install server.py --name "YouTrack MCP"

# With environment variables
mcp install server.py -v YOUTRACK_URL=https://your-instance.youtrack.cloud -v YOUTRACK_TOKEN=your-token
mcp install server.py -f .env

Step 2: Activate server

1. Open Claude Desktop
2. Go to Settings -> MCP Servers
3. Make sure "YouTrack MCP Server" is listed and activated

Available Tools

The server provides the following tools for working with YouTrack:

• youtrack_search_issues - Search for issues
• youtrack_get_issue - Get detailed information about an issue
• youtrack_update_issue - Update an issue
• youtrack_add_comment - Add a comment to an issue

Usage Examples

Search for issues:

{
  "type": "tool_call",
  "name": "youtrack_search_issues",
  "parameters": {
    "query": "project: YourProject",
    "top": 10
  }
}

Get issue information:

{
  "type": "tool_call",
  "name": "youtrack_get_issue",
  "parameters": {
    "issue_id": "YourProject-123"
  }
}

Add a comment:

{
  "type": "tool_call",
  "name": "youtrack_add_comment",
  "parameters": {
    "issue_id": "YourProject-123",
    "comment_text": "New comment for the issue"
  }
}

Access resources:

{
  "type": "resource_request",
  "uri": "server://info"
}

Architecture

The MCP server is built using the official Python SDK for Model Context Protocol, ensuring full compatibility with the MCP specification.

Main components:

• server.py - MCP server with tool and resource definitions
• youtrack_api.py - Functions for interacting with YouTrack API

Development and extension

To add new tools or resources, use the @mcp.tool() and @mcp.resource() decorators in the server.py file.

Example of adding a new tool:

@mcp.tool()
def youtrack_create_issue(project_id: str, summary: str, description: str = None) -> Dict[str, Any]:
    """
    Create a new issue in YouTrack.
    
    Args:
        project_id: The ID of the project
        summary: Issue summary
        description: Optional issue description
    """
    # Add implementation here
    return {"status": "success", "issue_id": "PROJECT-123"}