# YouTrack MCP Server

A comprehensive Model Context Protocol (MCP) server for JetBrains YouTrack. Provides full REST API access through 44 tools for AI agents.

## Features

- 44 tools covering issues, comments, projects, sprints, custom fields, time tracking, tags, users, activities, attachments, saved queries, and batch commands
- Works with any YouTrack instance (Cloud or Server)
- Zero config -- just set two environment variables
- Full YouTrack query language support
- Optimized API calls with selective field loading

## Quick Start

```bash
npx @abdullahtas/youtrack-mcp-server
```

Requires two environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `YOUTRACK_URL` | Yes | Your YouTrack instance URL (e.g. `https://your-org.youtrack.cloud`) |
| `YOUTRACK_TOKEN` | Yes | Permanent token for authentication |

**How to get a token:** YouTrack Profile -> Authentication -> New token. Grant the scope needed for your use case (typically `YouTrack`).

## Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "youtrack": {
      "command": "npx",
      "args": ["-y", "@abdullahtas/youtrack-mcp-server"],
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}
```

## Usage with Claude Code

```bash
claude mcp add youtrack -- env YOUTRACK_URL=https://your-instance.youtrack.cloud YOUTRACK_TOKEN=perm:xxx npx -y @abdullahtas/youtrack-mcp-server
```

## Available Tools

### Issues

| Tool | Description |
|------|-------------|
| `create_issue` | Create a new issue in a YouTrack project |
| `get_issue` | Get details of a specific issue by its readable ID (e.g. "BC-123") |
| `update_issue` | Update an existing issue (summary and/or description) |
| `delete_issue` | Delete an issue by its readable ID |
| `search_issues` | Search for issues using YouTrack query language |
| `link_issues` | Link two issues together with a specified link type |
| `get_issue_links` | Get all links for a specific issue |

### Comments

| Tool | Description |
|------|-------------|
| `get_comments` | Get comments for a specific issue |
| `add_comment` | Add a comment to an issue |
| `update_comment` | Update an existing comment on an issue |
| `delete_comment` | Delete a comment from an issue |

### Projects

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects in YouTrack |
| `get_project` | Get details of a specific project |
| `get_project_issues` | Get issues belonging to a specific project, optionally filtered by query |

### Agile & Sprints

| Tool | Description |
|------|-------------|
| `list_agile_boards` | List all agile boards in YouTrack |
| `get_agile_board` | Get details of a specific agile board including its sprints |
| `list_sprints` | List all sprints for a specific agile board |
| `get_sprint` | Get details of a specific sprint including its issues |
| `get_current_sprint` | Get the current active sprint for a specific agile board |
| `create_sprint` | Create a new sprint on an agile board |
| `update_sprint` | Update an existing sprint on an agile board |
| `add_issue_to_sprint` | Add an issue to a sprint using its readable ID |

### Custom Fields

| Tool | Description |
|------|-------------|
| `get_issue_custom_fields` | Get all custom fields for a specific issue |
| `update_custom_field` | Update a custom field value on an issue |
| `get_project_custom_fields` | Get all custom field definitions for a project |

### Time Tracking

| Tool | Description |
|------|-------------|
| `get_work_items` | Get time tracking work items for an issue |
| `add_work_item` | Add a time tracking work item to an issue |
| `update_work_item` | Update an existing time tracking work item |
| `delete_work_item` | Delete a time tracking work item from an issue |

### Tags

| Tool | Description |
|------|-------------|
| `list_tags` | List all issue tags in YouTrack |
| `create_tag` | Create a new issue tag |
| `add_tag` | Add a tag to an issue |
| `remove_tag` | Remove a tag from an issue |

### Users

| Tool | Description |
|------|-------------|
| `get_current_user` | Get the currently authenticated YouTrack user |
| `list_users` | List YouTrack users |
| `get_user` | Get a specific YouTrack user by ID |

### Activities

| Tool | Description |
|------|-------------|
| `get_issue_activities` | Get activity history for a specific issue |
| `get_activities` | Get global activity stream across all issues |

### Attachments

| Tool | Description |
|------|-------------|
| `get_attachments` | Get all attachments for an issue |
| `delete_attachment` | Delete an attachment from an issue |

### Saved Queries

| Tool | Description |
|------|-------------|
| `list_saved_queries` | List all saved search queries in YouTrack |
| `create_saved_query` | Create a new saved search query |

### Power Tools

| Tool | Description |
|------|-------------|
| `execute_command` | Execute a YouTrack command on one or more issues (e.g. "State In Progress", "Assignee me") |
| `raw_query` | Execute a raw YouTrack query and return issues with custom fields specification |

## License

MIT