Yandex Tracker MCP Server

mcp-name: io.github.aikts/yandex-tracker-mcp

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Yandex Tracker APIs. This server provides secure, authenticated access to Yandex Tracker issues, queues, comments, worklogs, and search functionality with optional Redis caching for improved performance.

Documentation in Russian is available here / Документация на русском языке доступна здесь.

Features

• Complete Queue Management: List and access all available Yandex Tracker queues with pagination support and tag retrieval

• User Management: Retrieve user account information, including login details, email addresses, license status, and organizational data

• Issue Operations: Retrieve detailed issue information, comments, related links, worklogs, and attachments

• Field Management: Access global fields, queue-specific local fields, statuses, and issue types

• Advanced Query Language: Full Yandex Tracker Query Language support with complex filtering, sorting, and date functions

• Performance Caching: Optional Redis caching layer for improved response times

• Security Controls: Configurable queue access restrictions and secure token handling

• Multiple Transport Options: Support for stdio, SSE (deprecated), and HTTP transports for flexible integration

• OAuth 2.0 Authentication: Dynamic token-based authentication with automatic refresh support as an alternative to static API tokens

• Organization Support: Compatible with both standard and cloud organization IDs

Organization ID Configuration

Choose one of the following based on your Yandex organization type:

• Yandex Cloud Organization: Use TRACKER_CLOUD_ORG_ID env var later for Yandex Cloud-managed organizations

• Yandex 360 Organization: Use TRACKER_ORG_ID env var later for Yandex 360 organizations

You can find your organization ID in the Yandex Tracker URL or organization settings.

MCP Client Configuration

Installing extension in Claude Desktop

Yandex Tracker MCP Server can be one-click installed in Claude Desktop as and extension.

Prerequisites

There is only one requirement - python 3.12 must be installed on your system.

For macOS users, you can install it using the following command:

Installation

1. Download the *.dxt file from GitHub Releases for your OS and platform.

2. Double-click the downloaded file to install it in Claude Desktop.

3. Provide your Yandex Tracker OAuth token when prompted.

4. Make sure extension is enabled - now you may use this MCP Server.

Manual installation

Prerequisites

• uv installed globally

• Valid Yandex Tracker API token with appropriate permissions

The following sections show how to configure the MCP server for different AI clients. You can use either uvx yandex-tracker-mcp@latest or the Docker image ghcr.io/aikts/yandex-tracker-mcp:latest. Both require these environment variables:

• Authentication (one of the following):

  • TRACKER_TOKEN - Your Yandex Tracker OAuth token

  • TRACKER_IAM_TOKEN - Your IAM token

  • TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY - Service account credentials

• TRACKER_CLOUD_ORG_ID or TRACKER_ORG_ID - Your Yandex Cloud (or Yandex 360) organization ID

Configuration file path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Using uvx:

Using Docker:

Using uvx:

Using Docker:

Configuration file path:

• Project-specific: .cursor/mcp.json in your project directory

• Global: ~/.cursor/mcp.json

Using uvx:

Using Docker:

Configuration file path:

• ~/.codeium/windsurf/mcp_config.json

Access via: Windsurf Settings → Cascade tab → Model Context Protocol (MCP) Servers → "View raw config"

Using uvx:

Using Docker:

Configuration file path:

• ~/.config/zed/settings.json

Access via: Cmd+, (macOS) or Ctrl+, (Linux/Windows) or command palette: "zed: open settings"

Note: Requires Zed Preview version for MCP support.

Using uvx:

Using Docker:

Configuration file path:

• Workspace: .vscode/mcp.json in your project directory

• Global: VS Code settings.json

Option 1: Workspace Configuration (Recommended for security)

Create .vscode/mcp.json:

Using uvx:

Using Docker:

Option 2: Global Configuration

Add to VS Code settings.json:

Using uvx:

Using Docker:

For other MCP-compatible clients, use the standard MCP server configuration format:

Using uvx:

Using Docker:

Important Notes:

• Replace placeholder values with your actual credentials

• Restart your AI client after configuration changes

• Ensure uvx is installed and available in your system PATH

• For production use, consider using environment variables instead of hardcoding tokens

Available MCP Tools

The server exposes the following tools through the MCP protocol:

Queue Management

• queues_get_all: List all available Yandex Tracker queues

  • Returns paginated queue information

  • Respects TRACKER_LIMIT_QUEUES restrictions

• queue_get_local_fields: Get local fields for a specific queue

  • Parameters: queue_id (string, queue key like "SOMEPROJECT")

  • Returns queue-specific custom fields with id, name, and key

  • Respects TRACKER_LIMIT_QUEUES restrictions

• queue_get_tags: Get all tags for a specific queue

  • Parameters: queue_id (string, queue key like "SOMEPROJECT")

  • Returns list of available tags in the specified queue

  • Respects TRACKER_LIMIT_QUEUES restrictions

• queue_get_versions: Get all versions for a specific queue

  • Parameters: queue_id (string, queue key like "SOMEPROJECT")

  • Returns list of available versions in the specified queue with details like name, description, dates, and status

  • Respects TRACKER_LIMIT_QUEUES restrictions

User Management

• users_get_all: Get information about user accounts registered in the organization

  • Parameters:

    • per_page (optional): Number of users per page (default: 50)

    • page (optional): Page number to return (default: 1)

  • Returns paginated list of users with login, email, license status, and organizational details

  • Includes user metadata such as external status, dismissal status, and notification preferences

• user_get: Get information about a specific user by login or UID

  • Parameters: user_id (string, user login like "john.doe" or UID like "12345")

  • Returns detailed user information including login, email, license status, and organizational details

  • Supports both user login names and numeric user IDs for flexible identification

• user_get_current: Get information about the current authenticated user

  • No parameters required

  • Returns detailed information about the user associated with the current authentication token

  • Includes login, email, display name, and organizational details for the authenticated user

• users_search: Search user based on login, email or real name (first or last name, or both)

  • Parameters: login_or_email_or_name (string, user login, email or real name to search for)

  • Returns either single user or multiple users if several match the query or an empty list if no users matched

  • Uses fuzzy matching for real names with a similarity threshold of 80%

  • Prioritizes exact matches for login and email over fuzzy name matches

Field Management

• get_global_fields: Get all global fields available in Yandex Tracker

  • Returns complete list of global fields that can be used in issues

  • Includes field schema, type information, and configuration

Status and Type Management

• get_statuses: Get all available issue statuses

  • Returns complete list of issue statuses that can be assigned

  • Includes status IDs, names, and type information

• get_issue_types: Get all available issue types

  • Returns complete list of issue types for creating/updating issues

  • Includes type IDs, names, and configuration details

• get_priorities: Get all available issue priorities

  • Returns complete list of priorities that can be assigned to issues

  • Includes priority keys, names, and order information

Issue Operations

• issue_get: Retrieve detailed issue information by ID

  • Parameters:

    • issue_id (string, format: "QUEUE-123")

    • include_description (boolean, optional, default: true): Whether to include issue description in the result. Can be large, so use only when needed.

  • Returns complete issue data including status, assignee, description, etc.

• issue_get_url: Generate web URL for an issue

  • Parameters: issue_id (string)

  • Returns: https://tracker.yandex.ru/{issue_id}

• issue_get_comments: Fetch all comments for an issue

  • Parameters: issue_id (string)

  • Returns chronological list of comments with metadata

• issue_get_links: Get related issue links

  • Parameters: issue_id (string)

  • Returns links to related, blocked, or duplicate issues

• issue_get_worklogs: Retrieve worklog entries

  • Parameters: issue_ids (array of strings)

  • Returns time tracking data for specified issues

• issue_get_attachments: Get attachments for an issue

  • Parameters: issue_id (string, format: "QUEUE-123")

  • Returns list of attachments with metadata for the specified issue

• issue_get_checklist: Get checklist items of an issue

  • Parameters: issue_id (string, format: "QUEUE-123")

  • Returns list of checklist items including text, status, assignee, and deadline information

Search and Discovery

• issues_find: Search issues using Yandex Tracker Query Language

  • Parameters:

    • query (required): Query string using Yandex Tracker Query Language syntax

    • include_description (boolean, optional, default: false): Whether to include issue description in the issues result. Can be large, so use only when needed.

    • fields (list of strings, optional): Fields to include in the response. Helps optimize context window usage by selecting only needed fields. If not specified, returns all available fields.

    • page (optional): Page number for pagination (default: 1)

    • per_page (optional): Number of items per page (default: 100). May be decreased if results exceed context window.

  • Returns up to specified number of issues per page

• issues_count: Count issues matching a query using Yandex Tracker Query Language

  • Parameters:

    • query (required): Query string using Yandex Tracker Query Language syntax

  • Returns the total count of issues matching the specified criteria

  • Supports all query language features: field filtering, date functions, logical operators, and complex expressions

  • Useful for analytics, reporting, and understanding issue distribution without retrieving full issue data

http Transport

The MCP server can also be run in streamable-http mode for web-based integrations or when stdio transport is not suitable.

streamable-http Mode Environment Variables

Starting the streamable-http Server

You may skip configuring TRACKER_CLOUD_ORG_ID or TRACKER_ORG_ID if you are using the following format when connecting to MCP Server (example for Claude Code):

or

You may also skip configuring global TRACKER_TOKEN environment variable if you choose to use OAuth 2.0 authentication (see below).

OAuth 2.0 Authentication

The Yandex Tracker MCP Server supports OAuth 2.0 authentication as a secure alternative to static API tokens. When configured, the server acts as an OAuth provider, facilitating authentication between your MCP client and Yandex OAuth services.

How OAuth Works

The MCP server implements a standard OAuth 2.0 authorization code flow:

1. Client Registration: Your MCP client registers with the server to obtain client credentials

2. Authorization: Users are redirected to Yandex OAuth to authenticate

3. Token Exchange: The server exchanges authorization codes for access tokens

4. API Access: Clients use bearer tokens for all API requests

5. Token Refresh: Expired tokens can be refreshed without re-authentication

OAuth Configuration

To enable OAuth authentication, set the following environment variables:

Setting Up Yandex OAuth Application

1. Go to Yandex OAuth and create a new application

2. Set the callback URL to: {MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback

3. Request the following permissions:

   • tracker:read - Read permissions for Tracker

   • tracker:write - Write permissions for Tracker

4. Save your Client ID and Client Secret

OAuth vs Static Token Authentication

OAuth Mode Limitations

• Currently, the OAuth mode requires the MCP server to be publicly accessible for callback URLs

• OAuth mode is best suited for interactive clients that support web-based authentication flows

Using OAuth with MCP Clients

When OAuth is enabled, MCP clients will need to:

1. Support OAuth 2.0 authorization code flow

2. Handle token refresh when access tokens expire

3. Store refresh tokens securely for persistent authentication

Note: Not all MCP clients currently support OAuth authentication. Check your client's documentation for OAuth compatibility.

Example configuration for Claude Code:

OAuth Data Storage

The MCP server supports two different storage backends for OAuth data (client registrations, access tokens, refresh tokens, and authorization states):

InMemory Store (Default)

The in-memory store keeps all OAuth data in server memory. This is the default option and requires no additional configuration.

Characteristics:

• Persistence: Data is lost when the server restarts

• Performance: Very fast access since data is stored in memory

• Scalability: Limited to single server instance

• Setup: No additional dependencies required

• Best for: Development, testing, or single-instance deployments where losing OAuth sessions on restart is acceptable

Configuration:

Redis Store

The Redis store provides persistent storage for OAuth data using a Redis database. This ensures OAuth sessions survive server restarts and enables multi-instance deployments.

Characteristics:

• Persistence: Data persists across server restarts

• Performance: Fast access with network overhead

• Scalability: Supports multiple server instances sharing the same Redis database

• Setup: Requires Redis server installation and configuration

• Best for: Production deployments, high availability setups, or when OAuth sessions must persist

Configuration:

Storage Behavior:

• Client Information: Stored persistently

• OAuth States: Stored with TTL (time-to-live) for security

• Authorization Codes: Stored with TTL and automatically cleaned up after use

• Access Tokens: Stored with automatic expiration based on token lifetime

• Refresh Tokens: Stored persistently until revoked

• Key Namespacing: Uses oauth:* prefixes to avoid conflicts with other Redis data

Important Notes:

• Both stores use the same Redis connection settings as the tools caching system

• When using Redis store, ensure your Redis instance is properly secured and accessible

• The OAUTH_STORE setting only affects OAuth data storage; tools caching uses TOOLS_CACHE_ENABLED

• Redis store uses JSON serialization for better cross-language compatibility and debugging

Authentication

Yandex Tracker MCP Server supports multiple authentication methods with a clear priority order. The server will use the first available authentication method based on this hierarchy:

Authentication Priority Order

1. Dynamic OAuth Token (highest priority)

   • When OAuth is enabled and a user authenticates via OAuth flow

   • Tokens are dynamically obtained and refreshed per user session

   • Supports both standard Yandex OAuth and Yandex Cloud federative OAuth

   • Required env vars: OAUTH_ENABLED=true, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, MCP_SERVER_PUBLIC_URL

   • Additional vars for federative OAuth: OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth, OAUTH_TOKEN_TYPE=Bearer, OAUTH_USE_SCOPES=false

2. Static OAuth Token

   • Traditional OAuth token provided via environment variable

   • Single token used for all requests

   • Required env var: TRACKER_TOKEN (your OAuth token)

3. Static IAM Token

   • IAM (Identity and Access Management) token for service-to-service authentication

   • Suitable for automated systems and CI/CD pipelines

   • Required env var: TRACKER_IAM_TOKEN (your IAM token)

4. Dynamic IAM Token (lowest priority)

   • Automatically retrieved using service account credentials

   • Token is fetched and refreshed automatically

   • Required env vars: TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY

Authentication Scenarios

Scenario 1: OAuth with Dynamic Tokens (Recommended for Interactive Use)

Scenario 2: Static OAuth Token (Simple Setup)

Scenario 3: Static IAM Token

Scenario 4: Dynamic IAM Token with Service Account

Scenario 5: Federative OAuth for OIDC Applications (Advanced)

This configuration enables authentication through Yandex Cloud OIDC applications, which is required for federated accounts in Yandex Cloud. Federated users authenticate through their organization's identity provider (IdP) and use this OAuth flow to access Yandex Tracker APIs.

Important Notes

• The server checks authentication methods in the order listed above

• Only one authentication method will be used at a time

• For production use, dynamic tokens (OAuth or IAM) are recommended for better security

• IAM tokens have a shorter lifetime than OAuth tokens and may need more frequent renewal

• When using service accounts, ensure the account has appropriate permissions for Yandex Tracker

Configuration

Environment Variables

Docker Deployment

Using Pre-built Image (Recommended)

Building the Image Locally

Docker Compose

Using pre-built image:

Building locally:

Development Setup

License

This project is licensed under the terms specified in the LICENSE file.

Support

For issues and questions:

• Review Yandex Tracker API documentation

• Submit issues at https://github.com/aikts/yandex-tracker-mcp/issues