# Yandex Tracker MCP Server: OAuth, Redis Caching, and the Org ID Trap

> The aikts/yandex-tracker-mcp project exposes Yandex Tracker to AI clients via MCP, with OAuth2, multiple transports, and optional Redis caching. The main friction is configuration: you must pick exactly one organization ID, and the wrong choice breaks every call.

**aikts/yandex-tracker-mcp** — Yandex Tracker MCP Server with OAuth2 support

- Repository: https://github.com/aikts/yandex-tracker-mcp
- Stars: 121 · Forks: 39
- Language: Python
- License: Apache-2.0
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/aikts-yandex-tracker-mcp

## What This Server Actually Does

The project is an MCP server, meaning it translates Model Context Protocol requests into Yandex Tracker API calls. It targets AI assistants like Claude Desktop, Claude Code, Cursor, and Windsurf, giving them structured access to Tracker data. The README lists a broad feature set: queue management, issue lifecycle, status transitions, custom fields, attachments, boards, sprints, worklogs, and search via the Yandex Tracker Query Language. There is also an opt-in for projects, portfolios, and goals through the entities API, controlled by the TRACKER_ENTITIES_ENABLED environment variable. The intended user is a developer or team that already uses Yandex Tracker and wants an AI copilot to manipulate tickets without exposing raw API tokens to the model. The server handles authentication, token refresh, and organization identification, so the AI client only sees MCP tool calls.

## How Authentication and Organization ID Work

Authentication supports three paths: a static OAuth token via TRACKER_TOKEN, an IAM token via TRACKER_IAM_TOKEN, or service account credentials via three separate variables (TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY). The README mentions OAuth2 with automatic refresh, but the exact refresh mechanism is not detailed in the provided material. The organization configuration is the sharp edge. You must set exactly one of TRACKER_CLOUD_ORG_ID for Yandex Cloud organizations or TRACKER_ORG_ID for Yandex 360 organizations. The README warns explicitly: setting both makes every Tracker call fail with 'Only one of org_id or cloud_org_id should be provided.' This is a hard constraint, not a recommendation. If your organization type is ambiguous, you will hit this error immediately. The README suggests finding the ID in the Tracker URL or organization settings, but it does not explain how to distinguish cloud from 360 visually. That is a gap in the documentation that could cost a new user a few minutes of debugging.

## Running It: Commands and Config Keys

The README gives two installation paths: uvx and Docker. For uvx, you run `uvx yandex-tracker-mcp@latest` and pass environment variables directly in the MCP client config. For Claude Desktop, the config file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows. A minimal entry looks like `{"mcpServers":{"yandex-tracker":{"command":"uvx","args":["yandex-tracker-mcp@latest"],"env":{"TRACKER_TOKEN":"your_tracker_token_here","TRACKER_CLOUD_ORG_ID":"your_cloud_org_id_here"}}}`. For Claude Code, the command is `claude mcp add yandex-tracker uvx yandex-tracker-mcp@latest -e TRACKER_TOKEN=your_tracker_token_here -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here -e TRANSPORT=stdio`. The Docker variant uses `ghcr.io/aikts/yandex-tracker-mcp:latest` with `-e` flags. There is also a one-click install for Claude Desktop via a `.mcpb` file downloaded from GitHub Releases. The TRANSPORT variable appears in the Claude Code example, but its full set of values is not enumerated in the truncated README. The project supports stdio, SSE (deprecated), and HTTP transports, so TRANSPORT=stdio is one valid option.

## Redis Caching: What It Buys and What It Costs

The README lists 'Optional Redis caching layer for improved response times' as a feature. The material does not specify which Redis client library is used, what cache keys look like, or whether cache invalidation happens on write operations. That is a notable omission. If the server caches issue reads but does not invalidate on updates, a user could see stale data after a transition. The README does not say. The benefit is clear for read-heavy workloads like search or listing queues, where repeated queries hit the cache instead of the Tracker API. The cost is operational: you need a Redis instance running, and you need to configure the connection details, which are not shown in the provided excerpts. There is no mention of a TRACKER_REDIS_URL variable or similar, so the exact config key remains unknown from this material. If you plan to use caching, you will need to read the full source or the Russian README to find the connection settings. That is a documentation gap that matters for production deployments.

## Transport Options and the SSE Deprecation

The server supports stdio, SSE, and HTTP transports. The README marks SSE as deprecated. That is a meaningful signal: if you are building a remote MCP client that relies on SSE, you should expect it to be removed in a future release. The HTTP transport is the likely replacement, but the README does not give configuration examples for it. The stdio transport is used in the Claude Code and Docker examples, which makes sense for local AI clients. For a remote deployment, you would need HTTP, but the setup steps are not in the truncated material. This is a practical limitation. The deprecation also suggests the maintainers are steering users toward HTTP, so new integrations should probably start there. The lack of concrete HTTP config examples in the README is a weakness, especially for teams that want to run the server on a separate host from the AI client.

## Security Controls and Queue Restrictions

The README mentions 'configurable queue access restrictions' under Security Controls. The exact mechanism is not detailed in the provided text. It could be a list of allowed queue IDs or a regex pattern, but the material does not say. This is important because Yandex Tracker can contain sensitive business data, and an AI assistant with write access could inadvertently modify issues. The README also mentions 'secure token handling,' but again, no specifics. The OAuth2 flow with automatic refresh is a positive sign, as it avoids long-lived static tokens. However, the service account path with a private key suggests the server can hold a private key in memory, which raises questions about key storage. The README does not specify whether the key is read from a file or an environment variable. Without that detail, a security-conscious user should inspect the source before deploying with service account credentials.

## Limitations and Wrong-Tool Cases

The most concrete limitation is the org ID constraint. Setting both IDs fails every call, and the README does not explain how to identify your organization type beyond a vague pointer to the URL or settings. A second limitation is the SSE deprecation, which narrows transport choices. Third, the Redis caching documentation is thin, leaving production tuning to guesswork. The project is also not a fit for read-only use cases. The tool schemas include create, update, and transition operations, so there is no obvious read-only mode. If you only want an AI to query issues without the risk of mutation, you would need to restrict permissions at the Yandex Tracker API level, not through this server. The README does not mention a read-only flag. For teams on Yandex 360, the TRACKER_ORG_ID variable is required, but the examples all use TRACKER_CLOUD_ORG_ID, which could lead to copy-paste errors.

## Alternatives and Comparison

The main alternative is writing a custom MCP server against the Yandex Tracker REST API directly. That gives you full control over which endpoints are exposed and how authentication is handled, but it requires building and maintaining your own tool schemas. The aikts project already provides comprehensive schemas for queues, issues, worklogs, and sprints, which saves significant development time. Another alternative is using Yandex Tracker's built-in automation or webhooks, but those do not integrate with MCP clients like Claude. A third option is a generic HTTP MCP server that proxies to any REST API, but that would lack the Yandex-specific query language support and the OAuth refresh logic. The real difference is effort: this project abstracts away the Tracker API quirks, but it also imposes its configuration choices, like the org ID rule and the SSE deprecation. If you have a simple Tracker setup and a small set of tools, a custom server might be lighter. If you need the full feature set, this project is the faster path.

## Maintenance, License, and Upgrade Cost

The repository is not archived and the last push was 2026-08-27, with releases 0.9.0, 0.8.0, and 0.7.3 coming out in a roughly one-month span. That suggests active maintenance. The license is Apache-2.0, which permits commercial use, modification, and redistribution with attribution. There is no mention of a migration guide between versions in the provided README. Upgrading likely means updating the uvx package or Docker image tag, but breaking changes are not documented in the material. The SSE deprecation implies a future removal, so upgrading to a version that drops SSE could break existing remote clients. The cost of maintenance is mostly configuration drift: if Yandex Tracker changes its API or the org ID format, you will need to track upstream releases. The project does not appear to have a dedicated upgrade document, so plan to read the release notes on each version bump.

## Conclusion

Adopt this server if your team lives in Yandex Tracker and wants AI assistants to read and write issues, queues, worklogs, and sprints through MCP. Skip it if you need read-only access or if your organization uses a non-standard Yandex setup that confuses the org ID selection. Before deploying, verify which organization type applies to you, set exactly one of TRACKER_ORG_ID or TRACKER_CLOUD_ORG_ID, and test a few search queries with the Query Language to confirm the tool schemas match your Tracker instance. The project is actively maintained, with releases as recent as August 2026, but the org ID constraint is a real operational risk that deserves a smoke test in a staging environment first.

## FAQ

### How do I install the Yandex Tracker MCP server?

Either run uvx yandex-tracker-mcp@latest, which needs uv installed globally, or use the published image ghcr.io/aikts/yandex-tracker-mcp:latest. For Claude Desktop there is also a .mcpb bundle on the releases page that installs by double-click and prompts for an OAuth token.

### Which authentication methods does the Yandex Tracker MCP server accept?

Three: TRACKER_TOKEN for a Yandex Tracker OAuth token, TRACKER_IAM_TOKEN for an IAM token, or the service account trio TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID and TRACKER_SA_PRIVATE_KEY. The OAuth path supports automatic refresh as an alternative to static API tokens.

### Why do all my Yandex Tracker MCP calls fail with an org_id error?

You have set both organization variables. Exactly one is required: TRACKER_CLOUD_ORG_ID for a Yandex Cloud organization or TRACKER_ORG_ID for Yandex 360. Setting both makes every call fail with Only one of org_id or cloud_org_id should be provided.

### What can the Yandex Tracker MCP server read and write?

Queues with pagination and tags, the full issue lifecycle with custom fields, attachments and workflow transitions, status transitions and closing with a resolution, global and queue-local fields, statuses, issue types, priorities, resolutions, agile boards and sprints, user account information, and the full Tracker Query Language with filtering, sorting and date functions.

### How do I enable the projects, portfolios and goals tools?

They are opt-in through the TRACKER_ENTITIES_ENABLED environment variable, and they are provided as separate read and write tools with explicit schemas for each entity type in the Tracker entities API.

### Does the Yandex Tracker MCP server support caching and remote transports?

Caching is an optional Redis layer for faster responses, with a redis:8-alpine compose service provided in the repository. Transports are stdio, HTTP, and SSE, with SSE marked deprecated.

## Sources

- [Official README](https://github.com/aikts/yandex-tracker-mcp#readme)
- [Project repository](https://github.com/aikts/yandex-tracker-mcp)
- [Release notes](https://github.com/aikts/yandex-tracker-mcp/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aikts-yandex-tracker-mcp