Ougha.MCP.YouTrack

A Model Context Protocol (MCP) server that integrates with JetBrains YouTrack's REST API, providing comprehensive tools for issue tracking, project management, and user administration.

Features

🎯 Issue Management

Create Issues: Create new issues with custom fields, assignees, priorities, and story points
⚠️ Important: Use project ID (e.g., "0-1") not shortName (e.g., "QM") to avoid 400 errors
Get Issue Details: Retrieve comprehensive issue information including comments and custom fields
Update Issues: Modify issue properties, assignees, states, custom fields, and story points
Search Issues: Basic and advanced search with YouTrack query language support
Add Comments: Add comments to existing issues
Delete Issues: Permanently delete issues (⚠️ WARNING: Cannot be undone!)

📋 Subtask Management

Create Subtasks: Create new subtasks and automatically link them to parent issues
Get Subtasks: Retrieve all subtasks of a parent issue with filtering options
Get Parent Issue: Find the parent issue of any subtask
Convert to Subtask: Convert existing issues to subtasks of other issues
Bulk Subtask Creation: Create multiple subtasks in one operation
Enhanced Issue Creation: Create issues as subtasks using the parentIssue parameter

🔗 Issue Relations & Dependencies

Issue Links: Create, view, and delete links between issues (depends on, blocks, relates to, etc.)
Link Types: Get available link types for projects
Dependencies: Manage task dependencies and relationships
Parent-Child Relations: Support for subtasks and parent issue relationships

📊 Story Points Management

Set Story Points: Assign story points to issues for agile estimation
Get Story Points: Retrieve story points for issues
Integrated Display: Story points shown in issue details and search results

📁 Project Management

List Projects: View all projects with filtering options for archived projects
Get Project Details: Retrieve detailed project information including leaders and descriptions

👥 User Management

Current User Info: Get information about the authenticated user
List Users: Browse users with search and filtering capabilities
Get User Details: Retrieve detailed user information by ID or login
Search Users: Find users by name or login with exact match options

🔍 Advanced Search

Advanced Issue Search: Use YouTrack's powerful query language for complex searches
My Issues: Get issues assigned to the current user with filtering
Recent Issues: Find recently updated issues within specified time ranges
User Search: Search for users by name with flexible matching

Installation

Prerequisites

Node.js 18.0.0 or higher
YouTrack instance with API access
YouTrack permanent token

Setup

Clone or download this repository

   git clone https://github.com/ugurhangul/youtrackMCP.git
   cd Ougha.MCP.YouTrack

Install dependencies

   npm install

Configure environment variables

   cp .env.example .env

Edit .env and set your YouTrack configuration: ``env YOUTRACK_URL=https://your-company.youtrack.cloud YOUTRACK_TOKEN=your-permanent-token YOUTRACK_TIMEOUT=30000 YOUTRACK_RATE_LIMIT=60 DEBUG=false ``

Build the server

   npm run build

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | YOUTRACK_URL | ✅ | - | Your YouTrack instance URL | | YOUTRACK_TOKEN | ✅ | - | YouTrack permanent token | | YOUTRACK_TIMEOUT | ❌ | 30000 | Request timeout in milliseconds | | YOUTRACK_RATE_LIMIT | ❌ | 60 | Max requests per minute | | DEBUG | ❌ | false | Enable debug logging |

Getting a YouTrack Token

Log in to your YouTrack instance
Go to your profile (click your avatar)
Navigate to Account Security → Tokens
Click New Token
Set appropriate permissions and create the token
Copy the token to your .env file

Usage

Running the Server

npm start

Using with Claude Desktop

Add the server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "ougha-youtrack": {
      "command": "node",
      "args": ["/absolute/path/to/Ougha.MCP.YouTrack/build/index.js"],
      "env": {
        "YOUTRACK_URL": "https://your-company.youtrack.cloud",
        "YOUTRACK_TOKEN": "your-permanent-token"
      }
    }
  }
}

Example Commands

Once connected to an MCP client, you can use natural language commands like:

"Create a new bug in project ABC with summary 'Login page not working'"
"Show me all issues assigned to me"
"Get details for issue ABC-123"
"List all projects"
"Search for issues updated in the last 7 days"
"Find user john.doe"
"Update issue ABC-123 to assign it to jane.smith"

Available Tools

Issue Management

create-issue - Create a new issue (now supports story points)
get-issue - Get issue details by ID
update-issue - Update an existing issue (now supports story points)
search-issues - Search issues with basic filters
add-comment - Add a comment to an issue
delete-issue - Delete an issue permanently (⚠️ WARNING: Cannot be undone!)

Issue Relations & Dependencies

get-issue-links - Get issue links and dependencies for an issue
create-issue-link - Create a link between two issues (dependency, relation, etc.)
delete-issue-link - Delete an issue link
get-link-types - Get available issue link types

Story Points

set-story-points - Set story points for an issue
get-story-points - Get story points for an issue

Project Management

list-projects - List all projects
get-project - Get project details

User Management

get-current-user - Get current user information
list-users - List users
get-user - Get user details

Advanced Search

search-issues-advanced - Advanced search with YouTrack query language
search-users-by-name - Search users by name
get-my-issues - Get issues assigned to current user
get-recent-issues - Get recently updated issues

Time Tracking

get-work-items - Get work items (time logs) for an issue
create-work-item - Create a work item (log time) for an issue
update-work-item - Update an existing work item
delete-work-item - Delete a work item
set-estimation - Set or update time estimation for an issue
get-time-summary - Get comprehensive time tracking summary for an issue

Time Tracking Examples

Creating Issues with Estimations

{
  "tool": "create-issue",
  "arguments": {
    "project": "0-1",
    "summary": "Implement new feature",
    "description": "Feature description",
    "estimationMinutes": 480,
    "assignee": "user-id"
  }
}

⚠️ Important: Use project ID (e.g., "0-1") not shortName (e.g., "QM"). Get the correct ID using list-projects tool.

Logging Time (Creating Work Items)

{
  "tool": "create-work-item",
  "arguments": {
    "issueId": "PROJECT-123",
    "duration": 120,
    "description": "Development work",
    "type": "Development"
  }
}

Getting Time Summary

{
  "tool": "get-time-summary",
  "arguments": {
    "issueId": "PROJECT-123"
  }
}

Issue Relations & Dependencies Examples

Creating Issue Dependencies

{
  "tool": "create-issue-link",
  "arguments": {
    "issueId": "PROJECT-123",
    "targetIssue": "PROJECT-456",
    "linkType": "Depends on",
    "direction": "OUTWARD"
  }
}

Getting Issue Links

{
  "tool": "get-issue-links",
  "arguments": {
    "issueId": "PROJECT-123"
  }
}

Getting Available Link Types

{
  "tool": "get-link-types",
  "arguments": {
    "projectId": "PROJECT-ID"
  }
}

Story Points Examples

Setting Story Points

{
  "tool": "set-story-points",
  "arguments": {
    "issueId": "PROJECT-123",
    "storyPoints": 8
  }
}

Creating Issues with Story Points

{
  "tool": "create-issue",
  "arguments": {
    "project": "0-1",
    "summary": "Implement user authentication",
    "description": "Add OAuth2 authentication",
    "storyPoints": 13,
    "estimationMinutes": 480,
    "assignee": "user-id"
  }
}

⚠️ Important: Use project ID (e.g., "0-1") not shortName (e.g., "QM"). Get the correct ID using list-projects tool.

YouTrack Query Language Examples

The search-issues-advanced tool supports YouTrack's powerful query language:

assignee: me State: Open
project: MyProject created: today
priority: Critical assignee: unassigned
updated: -7d .. today State: {In Progress}
reporter: john.doe project: ABC,XYZ

Error Handling

The server includes comprehensive error handling for:

Network connectivity issues
Authentication failures
Rate limiting (with automatic retry)
Invalid requests
YouTrack API errors

Rate Limiting

The server implements intelligent rate limiting:

Configurable requests per minute limit
Automatic request queuing when rate limited
Exponential backoff for failed requests
Respect for YouTrack's rate limiting headers

Development

Building

npm run build

Cleaning Build Files

npm run clean

Troubleshooting

Connection Issues

Verify your YouTrack URL is correct and accessible
Check that your permanent token has sufficient permissions
Ensure your YouTrack instance allows API access

Authentication Errors

Regenerate your permanent token in YouTrack
Verify the token has the necessary permissions:

Read issues, projects, users
Create/update issues (if needed)
Read project administration data

Rate Limiting

If you encounter rate limiting:

Reduce the YOUTRACK_RATE_LIMIT value
Check if other applications are using the same token
Consider using multiple tokens for different applications

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

Check the troubleshooting section above
Review YouTrack API documentation
Create an issue in this repository

Ougha.MCP.YouTrack