YouTrack MCP Server

A Model Context Protocol (MCP) server for YouTrack integration with AI assistants like Cursor IDE.

Features

• 🔍 Search Issues: Query YouTrack issues with flexible search syntax
• 📝 Issue Management: Create, update, and retrieve issue details
• 💬 Comments: Add comments to issues with Markdown support
• 📊 Project Information: List and explore YouTrack projects
• 🔐 Secure Authentication: Token-based authentication
• ⚡ Fast & Lightweight: Built with TypeScript and minimal dependencies

Installation

Using npx (Recommended)

npx clare-youtrack-mcp

Global Installation

npm install -g clare-youtrack-mcp

Configuration

Environment Variables

The server requires two environment variables:

• YOUTRACK_BASE_URL: Your YouTrack instance URL (e.g., https://your-company.youtrack.cloud/youtrack)
• YOUTRACK_TOKEN: Your YouTrack permanent token

Getting a YouTrack Token

1. Go to your YouTrack instance
2. Click on your profile icon → Profile Settings
3. Navigate to Authentication → Tokens
4. Click New Token
5. Give it a name and appropriate permissions
6. Copy the token (it will only be shown once!)

Usage with Cursor IDE

Add the following to your Cursor MCP configuration file (~/.cursor/mcp.json or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "youtrack": {
      "command": "npx",
      "args": ["-y", "clare-youtrack-mcp"],
      "env": {
        "YOUTRACK_BASE_URL": "https://your-company.youtrack.cloud/youtrack",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

After adding the configuration:

1. Save the file
2. Restart Cursor IDE
3. The YouTrack MCP server will be available in your AI assistant

Available Tools

1. get_issues

Search and retrieve YouTrack issues using a query.

Parameters:

• query (required): YouTrack search query (e.g., "project: MyProject State: Open")
• fields (optional): Comma-separated list of fields to return
• limit (optional): Maximum number of issues to return (default: 10)

Example:

Get all open issues in project ABC: query: "project: ABC State: Open"

2. get_issue

Get detailed information about a specific YouTrack issue.

Parameters:

• issueId (required): Issue ID (e.g., "PROJECT-123")
• fields (optional): Comma-separated list of fields to return

Example:

Get issue details for ABC-123

3. create_issue

Create a new YouTrack issue.

Parameters:

• project (required): Project ID or short name
• summary (required): Issue summary/title
• description (optional): Issue description

Example:

Create an issue in project ABC with title "Fix login bug" and description "Users cannot log in"

4. update_issue

Update an existing YouTrack issue.

Parameters:

• issueId (required): Issue ID (e.g., "PROJECT-123")
• summary (optional): New summary
• description (optional): New description

Example:

Update issue ABC-123 with new description "Updated requirements"

5. add_comment

Add a comment to a YouTrack issue.

Parameters:

• issueId (required): Issue ID (e.g., "PROJECT-123")
• text (required): Comment text (supports Markdown)

Example:

Add comment to ABC-123: "This issue has been resolved in the latest release"

6. get_projects

List all available YouTrack projects.

Example:

List all projects

Development

Prerequisites

• Node.js >= 18.0.0
• npm or yarn

Setup

# Clone the repository
git clone <your-repo-url>
cd youtrack-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Testing Locally

1. Build the project:

npm run build

2. Set environment variables:

export YOUTRACK_BASE_URL="https://your-company.youtrack.cloud/youtrack"
export YOUTRACK_TOKEN="perm:your-token-here"

3. Update your Cursor MCP configuration to use the local build:

{
  "mcpServers": {
    "youtrack": {
      "command": "node",
      "args": ["/path/to/youtrack-mcp-server/dist/index.js"],
      "env": {
        "YOUTRACK_BASE_URL": "https://your-company.youtrack.cloud/youtrack",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

4. Restart Cursor IDE

Troubleshooting

"Environment variables are required" Error

Make sure both YOUTRACK_BASE_URL and YOUTRACK_TOKEN are set in your MCP configuration.

Authentication Errors

• Verify your token is correct and hasn't expired
• Check that your token has the necessary permissions
• Ensure the base URL is correct and includes /youtrack if needed

Connection Issues

• Verify your YouTrack instance is accessible
• Check if your network allows connections to YouTrack
• Ensure there are no firewall or proxy issues

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on GitHub.