yandex-tracker-mcp

yandex-tracker-mcp is a comprehensive Model Context Protocol (MCP) server designed to let AI assistants interact with the Yandex Tracker API. It is secured through authentication and provides access to Yandex Tracker issues, queues, comments, worklogs, and search functionality, with optional Redis caching to improve response speed.

Key capabilities

• Queue management: List and access all available Yandex Tracker queues, with support for pagination, tag retrieval, and detailed metadata.
• Projects, portfolios, and goals: Separate read and write tools for each entity type in the Tracker "entities" API, selectively enabled via TRACKER_ENTITIES_ENABLED.
• User management: Retrieve user account information, including login details, email addresses, license status, and organization data.
• Full issue lifecycle: Create, read, update, and manage issues, with support for custom fields, attachments, and workflow transitions.
• Status workflow management: Perform status transitions, close issues with resolutions, and navigate complex workflows.
• Field management: Access global fields, queue-local fields, statuses, issue types, priorities, and resolutions.
• Boards and sprints: List agile boards and their sprints to find sprint IDs for issue planning.
• Advanced query language: Full support for the Yandex Tracker query language, including complex filtering, sorting, and date functions.
• Performance caching: An optional Redis cache layer to improve response times.
• Security controls: Configurable queue access restrictions and secure token handling.
• Multiple transports: Support for stdio, SSE (deprecated), and HTTP transports for flexible integration.
• OAuth 2.0 authentication: Dynamic token-based authentication with automatic refresh, as an alternative to static API tokens.
• Organization support: Compatible with standard organizations and cloud organization IDs.

Usage

Organization ID configuration

Choose one based on the Yandex organization type:

• Yandex Cloud organization: use the TRACKER_CLOUD_ORG_ID environment variable
• Yandex 360 organization: use TRACKER_ORG_ID environment variable The organization ID can be found in the Yandex Tracker URL or in the organization settings. Set only one of them; setting both will cause all Tracker calls to fail.

Installing the extension in Claude Desktop

This server can be installed as a one-click extension in Claude Desktop:

1. Download the *.mcpb file from GitHub Releases.
2. Double-click the downloaded file to install it in Claude Desktop.
3. Provide the Yandex Tracker OAuth token when prompted.
4. Make sure the extension is enabled.

Manual installation

Requires a global installation of uv and a valid Yandex Tracker API token with appropriate permissions. You can use uvx yandex-tracker-mcp@latest or the Docker image ghcr.io/aikts/yandex-tracker-mcp:latest. Both require environment variables:

• Authentication (choose one): TRACKER_TOKEN, TRACKER_IAM_TOKEN, or TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY (service account credentials).
• Organization (choose one): TRACKER_CLOUD_ORG_ID or TRACKER_ORG_ID.

Configuration paths for each client

• Claude Desktop: macOS is ~/Library/Application Support/Claude/claude_desktop_config.json, Windows is %APPDATA%\Claude\claude_desktop_config.json.
• Cursor: project-level is .cursor/mcp.json, global is ~/.cursor/mcp.json.
• Windsurf: ~/.codeium/windsurf/mcp_config.json, also available through Windsurf Settings → Cascade tab → Model Context Protocol (MCP) Servers → "View raw config".
• Zed: ~/.config/zed/settings.json, accessed via Cmd+, (macOS) or Ctrl+, (Linux/Windows) or the command palette "zed: open settings"; MCP is only supported in the Zed preview version.
• VS Code: .vscode/mcp.json for the workspace, VS Code settings.json for global.

After configuration changes, the AI client must be restarted; ensure uvx is installed and available in the system PATH; in production environments, use environment variables rather than hardcoded tokens.

Key points of available MCP tools

The server exposes various tools through the MCP protocol, involving the following usage details:

• Before issue_create, read queue_get_fields first, but system fields (such as parent, estimation) can be set even if they do not appear there; get_global_fields lists all fields owned by the organization.
• The resolution required by issue_close comes from queue_get_metadata's expand: ["issueTypesConfig"], and each issue type has its own set of resolutions.
• queues_get_all's hits/pages are only reported on servers without an allowlist for explicit single-page requests.
• A component is a label for grouping queue issues by product, process, or assignee, and its numeric id is used for the components parameter of issue_create/issue_update.
• TRACKER_LIMIT_QUEUES and TRACKER_READ_ONLY_QUEUES take effect through the queue to which the component belongs: component_update and component_delete first read the component to learn its queue, and components belonging to restricted queues are reported as not found.
• Projects, portfolios, and goals are separate entities exposed through the Tracker "entities" API, unlike queues; organization custom attributes are not modeled and are not returned. These tools are selectively enabled via TRACKER_ENTITIES_ENABLED=true (default false), and are not overridden by queue restrictions.
• links are only added, never replaced, and the API does not return them; existing links cannot be read back or deleted through this server, and updates containing only links are rejected.
• users_search first matches login names and email addresses exactly, then falls back to fuzzy name matching (80% similarity, up to three best matches).
• Queue-local fields are not listed separately; queue_get_fields returns them together with global fields.
• Templates are read-only aids: the API cannot create issues or comments from templates; you need to read the template and pass its values as parameters to write tools; macros like {{today}} are returned literally.
• Boards belong to the organization rather than queues, and TRACKER_LIMIT_QUEUES does not filter them; non-scrum boards have no sprints, and board_get_sprints is rejected.
• version expires on its own, and queue triggers and automations run immediately after issue_create and update it, so you should immediately re-read with issue_get before issue_update, or omit it to unconditionally update the latest version.
• Transitions should not be guessed; issue_execute_transition only accepts ids returned by issue_get_transitions.

streamable-http and OAuth 2.0

The server can run in streamable-http mode for web-based integrations or when the stdio transport is not suitable. OAuth 2.0 authentication serves as a secure alternative to static API tokens: the server acts as an OAuth provider, facilitating authentication between the MCP client and the Yandex OAuth service. The flow includes client registration, authorization redirect to Yandex OAuth, token exchange, API access, and token refresh. Enabling OAuth requires setting the corresponding environment variables; when OAUTH_USE_SCOPES=true (default), the tracker:read and tracker:write scopes are requested and enforced, and when TRACKER_READ_ONLY=true, only tracker:read is requested. You need to create an application in Yandex OAuth, with the callback URL set to {MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback, and request the tracker:read and tracker:write permissions, and save the Client ID and Client Secret. OAuth mode requires the MCP server to be publicly accessible to handle callbacks, making it best suited for interactive clients that support web-based authentication flows.