YouTrack MCP Server
A comprehensive Model Context Protocol (MCP) server for YouTrack integration, providing extensive tools for issue tracking, project management, workflow automation, and team collaboration.
Features
🎯 Issue Management
- CRUD Operations: Create, read, update, and delete issues
- Advanced Search: Search issues with complex filters and queries
- Bulk Operations: Update multiple issues at once
- Issue Linking: Manage relationships between issues
- Comments & Attachments: Full support for issue discussions and file attachments
- Work Items: Track time and work logs
📊 Project Management
- Project Operations: List, create, and manage projects
- Custom Fields: Define and manage custom field schemas
- Versions & Milestones: Track releases and project milestones
- Components: Organize issues by components/modules
👥 User & Team Management
- User Operations: List users, groups, and permissions
- Team Collaboration: Manage team assignments and roles
- Notifications: Handle user notifications and subscriptions
🔄 Workflow & Automation
- Workflow States: Manage issue states and transitions
- Custom Workflows: Define and execute custom workflows
- Automation Rules: Set up automated actions and triggers
📈 Analytics & Reporting
- Reports: Generate various project and issue reports
- Statistics: Get project statistics and metrics
- Time Tracking: Comprehensive time tracking and reporting
🏃♂️ Agile Features
- Agile Boards: Manage Kanban and Scrum boards
- Sprints: Create and manage sprint cycles
- Burndown Charts: Track progress with visual charts
Installation
Prerequisites
- Node.js 18.0.0 or higher
- YouTrack instance (Cloud or On-Premise)
- YouTrack API token or credentials
🚀 Lightweight Installation Options (Avoid Heavy node_modules)
Option 1: npx (Zero Installation - Recommended)```bash
Run directly without installing anything locally
npx youtrack-mcp
Test the installation
npx youtrack-mcp --help
With environment variables
YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud \
YOUTRACK_TOKEN=your-token \
npx youtrack-mcp
#### Option 2: **Global Installation** (Install Once, Use Everywhere)```bash
# Install globally from npm (only ~2MB)
npm install -g youtrack-mcp
# Test the installation
youtrack-mcp --help
# Run with environment variables
YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud \
YOUTRACK_TOKEN=your-token \
youtrack-mcp
Option 3: Using pnpm (70% less disk usage)```bash
Install pnpm globally (one time setup)
npm install -g pnpm
Clone and install with pnpm
git clone https://github.com/youtrack-mcp/youtrack-mcp.git
cd youtrack-mcp
pnpm install
pnpm run build
#### Option 4: **Docker Container** (Zero local dependencies)```bash
docker run -d --name youtrack-mcp \
-e YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud \
-e YOUTRACK_TOKEN=your-token \
ghcr.io/youtrack-mcp/youtrack-mcp:latest
Traditional Installation (Heavy node_modules)```bash
git clone https://github.com/youtrack-mcp/youtrack-mcp.git
cd youtrack-mcp
npm install
npm run build
### Claude Desktop Integration
Add to your `claude_desktop_config.json`:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
#### **Option 1: npx (Zero Installation - Recommended)**```json
{
"mcpServers": {
"youtrack": {
"command": "npx",
"args": ["youtrack-mcp"],
"env": {
"YOUTRACK_BASE_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_TOKEN": "your-permanent-token"
}
}
}
}
Option 2: Global Installation```json
{
"mcpServers": {
"youtrack": {
"command": "youtrack-mcp",
"env": {
"YOUTRACK_BASE_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_TOKEN": "your-permanent-token"
}
}
}
}
#### **Option 3: Local Development Build**```json
{
"mcpServers": {
"youtrack": {
"command": "node",
"args": ["/path/to/youtrack-mcp/build/index.js"],
"env": {
"YOUTRACK_BASE_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_TOKEN": "your-permanent-token"
}
}
}
}
Option 4: Docker Container```json
{
"mcpServers": {
"youtrack": {
"command": "docker",
"args": ["exec", "youtrack-mcp", "node", "build/index.js"],
"env": {}
}
}
}
## Configuration
### Authentication Methods
#### Permanent Token (Recommended)```env
YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud
YOUTRACK_TOKEN=your-permanent-token
To create a permanent token:
1. Go to YouTrack → Profile → Account Security → Tokens
2. Click "New Token"
3. Set appropriate permissions and scope
4. Copy the generated token
Username/Password (Not Recommended)```env
YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud
YOUTRACK_USERNAME=your-username
YOUTRACK_PASSWORD=your-password
### Advanced Configuration```env
# Performance
YOUTRACK_REQUEST_TIMEOUT=30000
YOUTRACK_MAX_RETRIES=3
YOUTRACK_DEFAULT_PAGE_SIZE=50
YOUTRACK_MAX_PAGE_SIZE=100
# Caching
YOUTRACK_ENABLE_CACHE=true
YOUTRACK_CACHE_TTL=300
# Debugging
YOUTRACK_DEBUG=true
Available Tools
Issue Management
| Tool | Description |
|---|---|
youtrack_list_issues |
List issues with filtering and pagination |
youtrack_get_issue |
Get detailed issue information |
youtrack_create_issue |
Create a new issue |
youtrack_update_issue |
Update existing issue |
youtrack_delete_issue |
Delete an issue |
youtrack_search_issues |
Advanced issue search with query syntax |
youtrack_add_comment |
Add comment to an issue |
youtrack_get_comments |
Get all comments for an issue |
youtrack_update_comment |
Update existing comment |
youtrack_delete_comment |
Delete a comment |
youtrack_add_attachment |
Add file attachment to issue |
youtrack_get_attachments |
Get all attachments for an issue |
youtrack_link_issues |
Create links between issues |
youtrack_get_issue_links |
Get all links for an issue |
Project Management
| Tool | Description |
|---|---|
youtrack_list_projects |
List all accessible projects |
youtrack_get_project |
Get detailed project information |
youtrack_create_project |
Create a new project |
youtrack_update_project |
Update project settings |
youtrack_delete_project |
Delete a project |
youtrack_get_project_custom_fields |
Get custom fields for project |
youtrack_add_project_custom_field |
Add custom field to project |
youtrack_list_project_versions |
List project versions/releases |
youtrack_create_project_version |
Create new version/release |
User Management
| Tool | Description |
|---|---|
youtrack_list_users |
List all users |
youtrack_get_user |
Get user details |
youtrack_get_current_user |
Get current authenticated user |
youtrack_list_groups |
List user groups |
youtrack_get_group |
Get group details |
youtrack_list_roles |
List available roles |
Workflow Management
| Tool | Description |
|---|---|
youtrack_get_workflow_states |
Get available workflow states |
youtrack_get_workflow_transitions |
Get possible state transitions |
youtrack_apply_workflow_command |
Apply workflow command to issue |
youtrack_get_issue_commands |
Get available commands for issue |
Time Tracking
| Tool | Description |
|---|---|
youtrack_add_work_item |
Add time tracking entry |
youtrack_get_work_items |
Get work items for issue |
youtrack_update_work_item |
Update work item |
youtrack_delete_work_item |
Delete work item |
youtrack_get_time_tracking_report |
Generate time tracking report |
Reports & Analytics
| Tool | Description |
|---|---|
youtrack_get_project_statistics |
Get project statistics |
youtrack_get_issue_statistics |
Get issue-related statistics |
youtrack_generate_report |
Generate custom reports |
youtrack_get_burndown_data |
Get burndown chart data |
Agile & Boards
| Tool | Description |
|---|---|
youtrack_list_agile_boards |
List all agile boards |
youtrack_get_agile_board |
Get agile board details |
youtrack_create_agile_board |
Create new agile board |
youtrack_update_agile_board |
Update agile board |
youtrack_list_sprints |
List sprints for board |
youtrack_create_sprint |
Create new sprint |
youtrack_update_sprint |
Update sprint details |
Usage Examples
Creating an Issue```
Create a new bug report with title "Login button not working" in project "WEB" with high priority
### Searching Issues```
Find all open issues assigned to john.doe in the mobile project created in the last 30 days
Project Management```
List all projects and show their current status and team members
### Time Tracking```
Add 2 hours of development work to issue WEB-123 with description "Implemented login validation"
Workflow Management```
Move issue WEB-123 to "In Progress" state and assign it to jane.smith
## Development
### Testing Installation```bash
# Run comprehensive tests
./examples.sh
# Test specific components
./examples.sh npx # Test npx installation
./examples.sh global # Test global installation
./examples.sh claude # Generate Claude configs
./examples.sh docker # Test Docker setup
Building```bash
npm run build
### Development Mode```bash
npm run dev
Watch Mode```bash
npm run watch
### Testing```bash
npm test
npm run test:npx # Test npx functionality
npm run test:global # Test global installation
Linting```bash
npm run lint
npm run lint:fix
### Debugging with MCP Inspector```bash
npm run inspector
API Documentation
This MCP server follows YouTrack's REST API structure. For detailed API reference, visit:
- YouTrack REST API Documentation
- YouTrack API Reference
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
- Issues: GitHub Issues
- Documentation: API Documentation
- Community: Discussions
Acknowledgments
- JetBrains YouTrack for the excellent issue tracking platform
- Model Context Protocol for the standardized integration framework
- Anthropic Claude for AI assistant integration