YouTrack MCP TypeScript Server

A Model Context Protocol (MCP) server for YouTrack integration, providing a standardized interface for LLMs to interact with YouTrack's issue tracking, agile management, and knowledge base features.

Features

• Issue Management

  • Create, read, update, delete issues
  • Add comments and attachments
  • Search issues with advanced filtering
  • Track issue time and estimation

• Agile & Sprint Management

  • Create and manage sprints
  • Assign issues to sprints
  • Track sprint progress

• State Management & Workflows

  • Transition issues through states
  • Start working on issues with automatic assignment
  • Complete issues with proper resolution

• Knowledge Base Integration

  • Create and manage articles
  • Link issues to knowledge base articles
  • Search knowledge base content

• Project Management

  • List and filter projects
  • Get project details and customization options

Installation

# Clone the repository
git clone https://github.com/itsalfredakku/youtrack-mcp.git
cd youtrack-mcp-ts

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Copy the example environment file and configure it with your YouTrack instance details:

cp .env.example .env

Edit the .env file with your specific configuration:

# YouTrack instance URL (without trailing slash)
YOUTRACK_URL=https://your-instance.youtrack.cloud

# YouTrack permanent token
# Generate from: Profile > Account Security > Tokens
YOUTRACK_TOKEN=your-permanent-token-here

# Optional: Default project ID
PROJECT_ID=PROJECT-1

# Optional: Enable webhooks (true/false)
ENABLE_WEBHOOKS=false

# Optional: Webhook server port (default: 3000)
WEBHOOK_PORT=3000

# Optional: Webhook secret for signature verification
WEBHOOK_SECRET=your-webhook-secret

# Optional: Log level (error, warn, info, debug)
LOG_LEVEL=info

# Optional: Cache TTL in milliseconds (default: 300000 = 5 minutes)
CACHE_TTL=300000

# Optional: Enable cache (true/false, default: true)
CACHE_ENABLED=true

Usage

Starting the Server

# Start the MCP server
npm start

# Start in development mode with auto-reload
npm run dev

Interacting with the Server

The YouTrack MCP server exposes tools following the Model Context Protocol. LLM applications can discover and use these tools to interact with YouTrack.

Example: Creating an Issue

{
  "tool": "create_issue",
  "params": {
    "projectId": "PROJECT-1",
    "summary": "Implement new feature",
    "description": "We need to implement the new feature as described in the specs.",
    "type": "Task",
    "priority": "Normal"
  }
}

Example: Searching Issues

{
  "tool": "search_issues",
  "params": {
    "query": "project: PROJECT-1 #bug state: Open",
    "limit": 10
  }
}

Example: Starting Work on an Issue

{
  "tool": "start_working_on_issue",
  "params": {
    "issueId": "PROJECT-1-123",
    "comment": "Starting implementation of this feature",
    "estimatedTime": "2d"
  }
}

Available Tools

The server provides 60+ tools for interacting with YouTrack. Here are some of the most commonly used:

Issue Management

• create_issue - Create a new issue
• get_issue - Get issue details
• update_issue - Update an issue
• add_issue_comment - Add a comment to an issue
• search_issues - Search for issues

Agile & Sprint Management

• list_sprints - List all sprints
• create_sprint - Create a new sprint
• assign_issue_to_sprint - Add an issue to a sprint
• get_sprint_issues - Get all issues in a sprint

State Management

• start_working_on_issue - Begin work on an issue
• change_issue_state - Change an issue's state
• complete_issue - Mark an issue as completed

Knowledge Base

• create_article - Create a knowledge base article
• update_article - Update an article
• get_article - Get article details
• search_articles - Search knowledge base articles

Project Management

• list_projects - List all accessible projects
• get_project_details - Get project information

Development

Prerequisites

• Node.js 18.x or later
• npm 8.x or later
• A YouTrack instance with API access

Development Workflow

# Install dependencies
npm install

# Start in development mode with auto-reload
npm run dev

# Run linting
npm run lint

# Run type checking
npm run type-check

# Build the project
npm run build

Project Structure

• src/index.ts - Main entry point
• src/youtrack-client.ts - YouTrack API client
• src/tools/ - Individual MCP tool implementations
• src/utils/ - Utility functions and helpers
• src/types/ - TypeScript type definitions
• src/config/ - Configuration management

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:queries
npm run test:issues

Troubleshooting

Common Issues

1. Authentication errors: Verify your YouTrack token has the necessary permissions and hasn't expired.

2. Project not found: Ensure the project ID exists and is accessible to your account.

3. API rate limiting: YouTrack may impose rate limits. Consider implementing retry logic for critical operations.

4. State transition errors: Some state transitions may be prohibited by your YouTrack workflow configuration.

Logs

Logs are stored in the logs directory:

• combined.log - All log entries
• error.log - Error-level logs only

Set the LOG_LEVEL environment variable to control logging verbosity (error, warn, info, debug).

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• YouTrack REST API
• Model Context Protocol (MCP)
• TypeScript
• Node.js