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 / Документац
Add this skill
npx mdskills install aikts/yandex-tracker-mcpComprehensive MCP server with extensive Yandex Tracker integration, excellent documentation and multiple authentication methods
1# Yandex Tracker MCP Server234567mcp-name: io.github.aikts/yandex-tracker-mcp89A 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.1011<a href="https://glama.ai/mcp/servers/@aikts/yandex-tracker-mcp">12 <img width="380" height="200" src="https://glama.ai/mcp/servers/@aikts/yandex-tracker-mcp/badge" />13</a>1415Documentation in Russian is available [here](README_ru.md) / Документация на русском языке доступна [здесь](README_ru.md).1617## Features1819- **Complete Queue Management**: List and access all available Yandex Tracker queues with pagination support, tag retrieval, and detailed metadata20- **User Management**: Retrieve user account information, including login details, email addresses, license status, and organizational data21- **Full Issue Lifecycle**: Create, read, update, and manage issues with support for custom fields, attachments, and workflow transitions22- **Status Workflow Management**: Execute status transitions, close issues with resolutions, and navigate complex workflows23- **Field Management**: Access global fields, queue-specific local fields, statuses, issue types, priorities, and resolutions24- **Advanced Query Language**: Full Yandex Tracker Query Language support with complex filtering, sorting, and date functions25- **Performance Caching**: Optional Redis caching layer for improved response times26- **Security Controls**: Configurable queue access restrictions and secure token handling27- **Multiple Transport Options**: Support for stdio, SSE (deprecated), and HTTP transports for flexible integration28- **OAuth 2.0 Authentication**: Dynamic token-based authentication with automatic refresh support as an alternative to static API tokens29- **Organization Support**: Compatible with both standard and cloud organization IDs3031### Organization ID Configuration3233Choose one of the following based on your Yandex organization type:3435- **Yandex Cloud Organization**: Use `TRACKER_CLOUD_ORG_ID` env var later for Yandex Cloud-managed organizations36- **Yandex 360 Organization**: Use `TRACKER_ORG_ID` env var later for Yandex 360 organizations3738You can find your organization ID in the Yandex Tracker URL or organization settings.394041## MCP Client Configuration4243### Installing extension in Claude Desktop4445Yandex Tracker MCP Server can be one-click installed in Claude Desktop as and [extension](https://www.anthropic.com/engineering/desktop-extensions).4647#### Installation48491. Download the `*.mcpb` file from [GitHub Releases](https://github.com/aikts/yandex-tracker-mcp/releases/latest).502. Double-click the downloaded file to install it in Claude Desktop. 513. Provide your Yandex Tracker OAuth token when prompted. 524. Make sure extension is enabled - now you may use this MCP Server.5354### Manual installation5556#### Prerequisites5758- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed globally59- Valid Yandex Tracker API token with appropriate permissions6061The 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:6263- Authentication (one of the following):64 - `TRACKER_TOKEN` - Your Yandex Tracker OAuth token65 - `TRACKER_IAM_TOKEN` - Your IAM token66 - `TRACKER_SA_KEY_ID`, `TRACKER_SA_SERVICE_ACCOUNT_ID`, `TRACKER_SA_PRIVATE_KEY` - Service account credentials67- `TRACKER_CLOUD_ORG_ID` or `TRACKER_ORG_ID` - Your Yandex Cloud (or Yandex 360) organization ID6869<details>70<summary><strong>Claude Desktop</strong></summary>7172**Configuration file path:**73- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`74- Windows: `%APPDATA%\Claude\claude_desktop_config.json`7576**Using uvx:**77```json78{79 "mcpServers": {80 "yandex-tracker": {81 "command": "uvx",82 "args": ["yandex-tracker-mcp@latest"],83 "env": {84 "TRACKER_TOKEN": "your_tracker_token_here",85 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",86 "TRACKER_ORG_ID": "your_org_id_here"87 }88 }89 }90}91```9293**Using Docker:**94```json95{96 "mcpServers": {97 "yandex-tracker": {98 "command": "docker",99 "args": [100 "run", "--rm", "-i",101 "-e", "TRACKER_TOKEN",102 "-e", "TRACKER_CLOUD_ORG_ID",103 "-e", "TRACKER_ORG_ID",104 "ghcr.io/aikts/yandex-tracker-mcp:latest"105 ],106 "env": {107 "TRACKER_TOKEN": "your_tracker_token_here",108 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",109 "TRACKER_ORG_ID": "your_org_id_here"110 }111 }112 }113}114```115116</details>117118<details>119<summary><strong>Claude Code</strong></summary>120121**Using uvx:**122```bash123claude mcp add yandex-tracker uvx yandex-tracker-mcp@latest \124 -e TRACKER_TOKEN=your_tracker_token_here \125 -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here \126 -e TRACKER_ORG_ID=your_org_id_here \127 -e TRANSPORT=stdio128```129130**Using Docker:**131```bash132claude mcp add yandex-tracker docker "run --rm -i -e TRACKER_TOKEN=your_tracker_token_here -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here -e TRACKER_ORG_ID=your_org_id_here -e TRANSPORT=stdio ghcr.io/aikts/yandex-tracker-mcp:latest"133```134135</details>136137<details>138<summary><strong>Cursor</strong></summary>139140**Configuration file path:**141- Project-specific: `.cursor/mcp.json` in your project directory142- Global: `~/.cursor/mcp.json`143144**Using uvx:**145```json146{147 "mcpServers": {148 "yandex-tracker": {149 "command": "uvx",150 "args": ["yandex-tracker-mcp@latest"],151 "env": {152 "TRACKER_TOKEN": "your_tracker_token_here",153 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",154 "TRACKER_ORG_ID": "your_org_id_here"155 }156 }157 }158}159```160161**Using Docker:**162```json163{164 "mcpServers": {165 "yandex-tracker": {166 "command": "docker",167 "args": [168 "run", "--rm", "-i",169 "-e", "TRACKER_TOKEN",170 "-e", "TRACKER_CLOUD_ORG_ID",171 "-e", "TRACKER_ORG_ID",172 "ghcr.io/aikts/yandex-tracker-mcp:latest"173 ],174 "env": {175 "TRACKER_TOKEN": "your_tracker_token_here",176 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",177 "TRACKER_ORG_ID": "your_org_id_here"178 }179 }180 }181}182```183184</details>185186<details>187<summary><strong>Windsurf</strong></summary>188189**Configuration file path:**190- `~/.codeium/windsurf/mcp_config.json`191192Access via: Windsurf Settings → Cascade tab → Model Context Protocol (MCP) Servers → "View raw config"193194**Using uvx:**195```json196{197 "mcpServers": {198 "yandex-tracker": {199 "command": "uvx",200 "args": ["yandex-tracker-mcp@latest"],201 "env": {202 "TRACKER_TOKEN": "your_tracker_token_here",203 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",204 "TRACKER_ORG_ID": "your_org_id_here"205 }206 }207 }208}209```210211**Using Docker:**212```json213{214 "mcpServers": {215 "yandex-tracker": {216 "command": "docker",217 "args": [218 "run", "--rm", "-i",219 "-e", "TRACKER_TOKEN",220 "-e", "TRACKER_CLOUD_ORG_ID",221 "-e", "TRACKER_ORG_ID",222 "ghcr.io/aikts/yandex-tracker-mcp:latest"223 ],224 "env": {225 "TRACKER_TOKEN": "your_tracker_token_here",226 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",227 "TRACKER_ORG_ID": "your_org_id_here"228 }229 }230 }231}232```233234</details>235236<details>237<summary><strong>Zed</strong></summary>238239**Configuration file path:**240- `~/.config/zed/settings.json`241242Access via: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows) or command palette: "zed: open settings"243244**Note:** Requires Zed Preview version for MCP support.245246**Using uvx:**247```json248{249 "context_servers": {250 "yandex-tracker": {251 "source": "custom",252 "command": {253 "path": "uvx",254 "args": ["yandex-tracker-mcp@latest"],255 "env": {256 "TRACKER_TOKEN": "your_tracker_token_here",257 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",258 "TRACKER_ORG_ID": "your_org_id_here"259 }260 }261 }262 }263}264```265266**Using Docker:**267```json268{269 "context_servers": {270 "yandex-tracker": {271 "source": "custom",272 "command": {273 "path": "docker",274 "args": [275 "run", "--rm", "-i",276 "-e", "TRACKER_TOKEN",277 "-e", "TRACKER_CLOUD_ORG_ID",278 "-e", "TRACKER_ORG_ID",279 "ghcr.io/aikts/yandex-tracker-mcp:latest"280 ],281 "env": {282 "TRACKER_TOKEN": "your_tracker_token_here",283 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",284 "TRACKER_ORG_ID": "your_org_id_here"285 }286 }287 }288 }289}290```291292</details>293294<details>295<summary><strong>GitHub Copilot (VS Code)</strong></summary>296297**Configuration file path:**298- Workspace: `.vscode/mcp.json` in your project directory299- Global: VS Code `settings.json`300301**Option 1: Workspace Configuration (Recommended for security)**302303Create `.vscode/mcp.json`:304305**Using uvx:**306```json307{308 "inputs": [309 {310 "type": "promptString",311 "id": "tracker-token",312 "description": "Yandex Tracker Token",313 "password": true314 },315 {316 "type": "promptString",317 "id": "cloud-org-id",318 "description": "Yandex Cloud Organization ID"319 },320 {321 "type": "promptString",322 "id": "org-id",323 "description": "Yandex Tracker Organization ID (optional)"324 }325 ],326 "servers": {327 "yandex-tracker": {328 "type": "stdio",329 "command": "uvx",330 "args": ["yandex-tracker-mcp@latest"],331 "env": {332 "TRACKER_TOKEN": "${input:tracker-token}",333 "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",334 "TRACKER_ORG_ID": "${input:org-id}",335 "TRANSPORT": "stdio"336 }337 }338 }339}340```341342**Using Docker:**343```json344{345 "inputs": [346 {347 "type": "promptString",348 "id": "tracker-token",349 "description": "Yandex Tracker Token",350 "password": true351 },352 {353 "type": "promptString",354 "id": "cloud-org-id",355 "description": "Yandex Cloud Organization ID"356 },357 {358 "type": "promptString",359 "id": "org-id",360 "description": "Yandex Tracker Organization ID (optional)"361 }362 ],363 "servers": {364 "yandex-tracker": {365 "type": "stdio",366 "command": "docker",367 "args": [368 "run", "--rm", "-i",369 "-e", "TRACKER_TOKEN",370 "-e", "TRACKER_CLOUD_ORG_ID",371 "-e", "TRACKER_ORG_ID",372 "ghcr.io/aikts/yandex-tracker-mcp:latest"373 ],374 "env": {375 "TRACKER_TOKEN": "${input:tracker-token}",376 "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",377 "TRACKER_ORG_ID": "${input:org-id}",378 "TRANSPORT": "stdio"379 }380 }381 }382}383```384385**Option 2: Global Configuration**386387Add to VS Code `settings.json`:388389**Using uvx:**390```json391{392 "github.copilot.chat.mcp.servers": {393 "yandex-tracker": {394 "type": "stdio",395 "command": "uvx",396 "args": ["yandex-tracker-mcp@latest"],397 "env": {398 "TRACKER_TOKEN": "your_tracker_token_here",399 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",400 "TRACKER_ORG_ID": "your_org_id_here"401 }402 }403 }404}405```406407**Using Docker:**408```json409{410 "github.copilot.chat.mcp.servers": {411 "yandex-tracker": {412 "type": "stdio",413 "command": "docker",414 "args": [415 "run", "--rm", "-i",416 "-e", "TRACKER_TOKEN",417 "-e", "TRACKER_CLOUD_ORG_ID",418 "-e", "TRACKER_ORG_ID",419 "ghcr.io/aikts/yandex-tracker-mcp:latest"420 ],421 "env": {422 "TRACKER_TOKEN": "your_tracker_token_here",423 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",424 "TRACKER_ORG_ID": "your_org_id_here"425 }426 }427 }428}429```430431</details>432433<details>434<summary><strong>Other MCP-Compatible Clients</strong></summary>435436For other MCP-compatible clients, use the standard MCP server configuration format:437438**Using uvx:**439```json440{441 "mcpServers": {442 "yandex-tracker": {443 "command": "uvx",444 "args": ["yandex-tracker-mcp@latest"],445 "env": {446 "TRACKER_TOKEN": "your_tracker_token_here",447 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",448 "TRACKER_ORG_ID": "your_org_id_here"449 }450 }451 }452}453```454455**Using Docker:**456```json457{458 "mcpServers": {459 "yandex-tracker": {460 "command": "docker",461 "args": [462 "run", "--rm", "-i",463 "-e", "TRACKER_TOKEN",464 "-e", "TRACKER_CLOUD_ORG_ID",465 "-e", "TRACKER_ORG_ID",466 "ghcr.io/aikts/yandex-tracker-mcp:latest"467 ],468 "env": {469 "TRACKER_TOKEN": "your_tracker_token_here",470 "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here",471 "TRACKER_ORG_ID": "your_org_id_here"472 }473 }474 }475}476```477478</details>479480**Important Notes:**481- Replace placeholder values with your actual credentials482- Restart your AI client after configuration changes483- Ensure `uvx` is installed and available in your system PATH484- For production use, consider using environment variables instead of hardcoding tokens485486## Available MCP Tools487488The server exposes the following tools through the MCP protocol:489490<details>491<summary><strong>Queue Management</strong></summary>492493- **`queues_get_all`**: List all available Yandex Tracker queues494 - Parameters:495 - `fields` (optional): Fields to include in the response (e.g., ["key", "name"]). Helps optimize context window usage by selecting only needed fields. If not specified, returns all available fields.496 - `page` (optional): Page number to return. If not specified, retrieves all pages automatically.497 - `per_page` (optional): Number of items per page (default: 100)498 - Returns paginated queue information with selective field inclusion499 - Respects `TRACKER_LIMIT_QUEUES` restrictions500501- **`queue_get_tags`**: Get all tags for a specific queue502 - Parameters: `queue_id` (string, queue key like "SOMEPROJECT")503 - Returns list of available tags in the specified queue504 - Respects `TRACKER_LIMIT_QUEUES` restrictions505506- **`queue_get_versions`**: Get all versions for a specific queue507 - Parameters: `queue_id` (string, queue key like "SOMEPROJECT")508 - Returns list of available versions in the specified queue with details like name, description, dates, and status509 - Respects `TRACKER_LIMIT_QUEUES` restrictions510511- **`queue_get_fields`**: Get fields for a specific queue512 - Parameters:513 - `queue_id` (string, required): Queue key like "SOMEPROJECT"514 - `include_local_fields` (boolean, optional, default: true): Whether to include queue-specific local fields515 - Returns list of global fields and optionally local (queue-specific) fields516 - Makes parallel requests to fetch both field types when `include_local_fields` is true517 - The `schema.required` property indicates whether a field is mandatory518 - Use this to find available and required fields before creating an issue with `issue_create` tool519 - Respects `TRACKER_LIMIT_QUEUES` restrictions520521- **`queue_get_metadata`**: Get detailed metadata about a specific queue522 - Parameters:523 - `queue_id` (string, required): Queue key like "SOMEPROJECT"524 - `expand` (array of strings, optional): Fields to expand in the response. Available options: `all`, `projects`, `components`, `versions`, `types`, `team`, `workflows`, `fields`, `issueTypesConfig`525 - Returns queue information including name, description, default type/priority, and optionally expanded data526 - Use `expand: ["issueTypesConfig"]` to get available resolutions for each issue type (needed for `issue_close` tool)527 - Respects `TRACKER_LIMIT_QUEUES` restrictions528529</details>530531<details>532<summary><strong>User Management</strong></summary>533534- **`users_get_all`**: Get information about user accounts registered in the organization535 - Parameters:536 - `per_page` (optional): Number of users per page (default: 50)537 - `page` (optional): Page number to return (default: 1)538 - Returns paginated list of users with login, email, license status, and organizational details539 - Includes user metadata such as external status, dismissal status, and notification preferences540541- **`user_get`**: Get information about a specific user by login or UID542 - Parameters: `user_id` (string, user login like "john.doe" or UID like "12345")543 - Returns detailed user information including login, email, license status, and organizational details544 - Supports both user login names and numeric user IDs for flexible identification545546- **`user_get_current`**: Get information about the current authenticated user547 - No parameters required548 - Returns detailed information about the user associated with the current authentication token549 - Includes login, email, display name, and organizational details for the authenticated user550551- **`users_search`**: Search user based on login, email or real name (first or last name, or both)552 - Parameters: `login_or_email_or_name` (string, user login, email or real name to search for)553 - Returns either single user or multiple users if several match the query or an empty list if no users matched554 - Uses fuzzy matching for real names with a similarity threshold of 80%555 - Prioritizes exact matches for login and email over fuzzy name matches556557</details>558559<details>560<summary><strong>Field Management</strong></summary>561562- **`get_global_fields`**: Get all global fields available in Yandex Tracker563 - Returns complete list of global fields that can be used in issues564 - Includes field schema, type information, and configuration565566</details>567568<details>569<summary><strong>Status and Type Management</strong></summary>570571- **`get_statuses`**: Get all available issue statuses572 - Returns complete list of issue statuses that can be assigned573 - Includes status IDs, names, and type information574575- **`get_issue_types`**: Get all available issue types576 - Returns complete list of issue types for creating/updating issues577 - Includes type IDs, names, and configuration details578579- **`get_priorities`**: Get all available issue priorities580 - Returns complete list of priorities that can be assigned to issues581 - Includes priority keys, names, and order information582583- **`get_resolutions`**: Get all available issue resolutions584 - Returns complete list of resolutions that can be used when closing issues585 - Includes resolution keys, names, descriptions, and order information586587</details>588589<details>590<summary><strong>Issue Operations</strong></summary>591592- **`issue_get`**: Retrieve detailed issue information by ID593 - Parameters:594 - `issue_id` (string, format: "QUEUE-123")595 - `include_description` (boolean, optional, default: true): Whether to include issue description in the result. Can be large, so use only when needed.596 - Returns complete issue data including status, assignee, description, etc.597598- **`issue_get_url`**: Generate web URL for an issue599 - Parameters: `issue_id` (string)600 - Returns: `https://tracker.yandex.ru/{issue_id}`601602- **`issue_get_comments`**: Fetch all comments for an issue603 - Parameters: `issue_id` (string)604 - Returns chronological list of comments with metadata605606- **`issue_add_comment`**: Add a comment to an issue607 - Parameters:608 - `issue_id` (string, required, format: "QUEUE-123")609 - `text` (string, required): Comment text (markdown supported by Tracker)610 - `summonees` (array of strings, optional): Users to summon (logins or IDs). **This is the API way to mention/call users** (notifications are triggered by this field, not by `@login` in text).611 - `maillist_summonees` (array of strings, optional): Mailing lists to summon (emails)612 - `markup_type` (string, optional): Use `md` for YFM (markdown)613 - `is_add_to_followers` (boolean, optional, default: true): Add comment author to followers614 - Returns created comment object615616- **`issue_update_comment`**: Update an existing comment in an issue617 - Parameters:618 - `issue_id` (string, required, format: "QUEUE-123")619 - `comment_id` (int, required): Comment ID620 - `text` (string, required): New comment text (markdown supported by Tracker)621 - `summonees` (array of strings, optional): Users to summon (logins or IDs)622 - `maillist_summonees` (array of strings, optional): Mailing lists to summon (emails)623 - `markup_type` (string, optional): Use `md` for YFM (markdown)624 - Returns updated comment object625626- **`issue_delete_comment`**: Delete a comment from an issue627 - Parameters:628 - `issue_id` (string, required, format: "QUEUE-123")629 - `comment_id` (int, required): Comment ID630 - Returns: `null` (success)631632- **`issue_get_links`**: Get related issue links633 - Parameters: `issue_id` (string)634 - Returns links to related, blocked, or duplicate issues635636- **`issue_get_worklogs`**: Retrieve worklog entries637 - Parameters: `issue_ids` (array of strings)638 - Returns time tracking data for specified issues639640- **`issue_add_worklog`**: Add a worklog entry (log spent time) to an issue641 - Parameters:642 - `issue_id` (string, required, format: "QUEUE-123")643 - `duration` (string, required): ISO-8601 duration (e.g. `PT1H30M`)644 - `comment` (string, optional): Worklog comment645 - `start` (datetime, optional): Work start datetime (UTC assumed if timezone is not provided)646 - Returns created worklog entry647648- **`issue_update_worklog`**: Update a worklog entry (spent time record) in an issue649 - Parameters:650 - `issue_id` (string, required, format: "QUEUE-123")651 - `worklog_id` (int, required): Worklog entry ID652 - `duration` (string, optional): ISO-8601 duration (e.g. `PT1H30M`)653 - `comment` (string, optional): Worklog comment654 - `start` (datetime, optional): Work start datetime (UTC assumed if timezone is not provided)655 - Returns updated worklog entry656657- **`issue_delete_worklog`**: Delete a worklog entry (spent time record) from an issue658 - Parameters:659 - `issue_id` (string, required, format: "QUEUE-123")660 - `worklog_id` (int, required): Worklog entry ID661 - Returns: `null` (success)662663- **`issue_get_attachments`**: Get attachments for an issue664 - Parameters: `issue_id` (string, format: "QUEUE-123")665 - Returns list of attachments with metadata for the specified issue666667- **`issue_get_checklist`**: Get checklist items of an issue668 - Parameters: `issue_id` (string, format: "QUEUE-123")669 - Returns list of checklist items including text, status, assignee, and deadline information670671- **`issue_get_transitions`**: Get possible status transitions for an issue672 - Parameters: `issue_id` (string, format: "QUEUE-123")673 - Returns list of available transitions that can be performed on the issue674 - Each transition includes an ID, display name, and target status information675676- **`issue_execute_transition`**: Execute a status transition for an issue677 - Parameters:678 - `issue_id` (string, required, format: "QUEUE-123"): The issue key679 - `transition_id` (string, required): The transition ID to execute. **IMPORTANT**: Must be one of the IDs returned by `issue_get_transitions` tool680 - `comment` (string, optional): Optional comment to add when executing the transition681 - `fields` (object, optional): Dictionary of additional fields to set during the transition. Common fields include `resolution` (e.g., 'fixed', 'wontFix') for closing issues, `assignee` for reassigning, etc.682 - Returns list of available transitions for the new status after the transition is executed683 - **Usage note**: You MUST first call `issue_get_transitions` to retrieve available transitions, then pass one of the returned transition IDs. Do NOT use arbitrary transition IDs.684685- **`issue_close`**: Close an issue with a resolution (convenience tool)686 - Parameters:687 - `issue_id` (string, required, format: "QUEUE-123"): The issue key688 - `resolution_id` (string, required): The resolution ID to set when closing (e.g., 'fixed', 'wontFix', 'duplicate')689 - `comment` (string, optional): Optional comment to add when closing the issue690 - Automatically finds a transition to a 'done' status and executes it with the specified resolution691 - Returns list of available transitions for the new (closed) status692 - **Usage note**: Before closing, you MUST:693 1. Call `issue_get` to retrieve the issue's `type` field694 2. Call `get_queue_metadata` with `expand: ["issueTypesConfig"]` to get available resolutions695 3. Choose a resolution from the `issueTypesConfig` entry matching the issue's type - each issue type has its own set of valid resolutions696697- **`issue_create`**: Create a new issue in a queue698 - Parameters:699 - `queue` (string, required): Queue key where to create the issue (e.g., 'MYQUEUE')700 - `summary` (string, required): Issue title/summary701 - `type` (int, optional): Issue type ID (from `get_issue_types` tool)702 - `description` (string, optional): Issue description703 - `assignee` (string or int, optional): Assignee login or UID704 - `priority` (string, optional): Priority key (from `get_priorities` tool)705 - `fields` (object, optional): Additional fields to set during issue creation. **IMPORTANT**: Before creating an issue, you MUST call `queue_get_fields` to get available fields (it returns both global and local fields by default). Fields with `schema.required=true` are mandatory. Use the field's `id` property as the key in this map (e.g., `{"fieldId": "value"}`)706 - Returns the newly created issue object with all standard issue fields707 - Respects `TRACKER_LIMIT_QUEUES` restrictions708709- **`issue_update`**: Update an existing issue710 - Parameters:711 - `issue_id` (string, required, format: "QUEUE-123"): The issue key to update712 - `summary` (string, optional): New issue title/summary713 - `description` (string, optional): New issue description714 - `markup_type` (string, optional): Markup type for description text (use 'md' for YFM markup)715 - `parent` (IssueUpdateParent, optional): Parent issue reference with `id` (string) and/or `key` (string, e.g., 'QUEUE-123')716 - `sprint` (array of IssueUpdateSprint, optional): Sprint assignments - array of objects with `id` (int) field717 - `type` (IssueUpdateType, optional): Issue type with `id` (string) and/or `key` (string, e.g., 'bug', 'task')718 - `priority` (IssueUpdatePriority, optional): Priority with `id` (string) and/or `key` (string, e.g., 'critical', 'normal')719 - `followers` (array of IssueUpdateFollower, optional): Followers - array of objects with `id` (string, user ID or login)720 - `project` (IssueUpdateProject, optional): Project with `primary` (int, main project shortId) and optional `secondary` (array of ints)721 - `attachment_ids` (array of strings, optional): IDs of temporary files to attach722 - `description_attachment_ids` (array of strings, optional): IDs of temporary files to embed in description723 - `tags` (array of strings, optional): Issue tags724 - `version` (int, optional): Issue version for optimistic locking - changes only made to current version725 - `fields` (object, optional): Additional fields to update. Use `queue_get_fields` to discover available fields.726 - Returns the updated issue object with all standard issue fields727 - Only provided fields are updated; omitted fields remain unchanged728 - Respects `TRACKER_LIMIT_QUEUES` restrictions729730</details>731732<details>733<summary><strong>Search and Discovery</strong></summary>734735- **`issues_find`**: Search issues using [Yandex Tracker Query Language](https://yandex.ru/support/tracker/ru/user/query-filter)736 - Parameters:737 - `query` (required): Query string using Yandex Tracker Query Language syntax738 - `include_description` (boolean, optional, default: false): Whether to include issue description in the issues result. Can be large, so use only when needed.739 - `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.740 - `page` (optional): Page number for pagination (default: 1)741 - `per_page` (optional): Number of items per page (default: 100). May be decreased if results exceed context window.742 - Returns up to specified number of issues per page743744- **`issues_count`**: Count issues matching a query using [Yandex Tracker Query Language](https://yandex.ru/support/tracker/ru/user/query-filter)745 - Parameters:746 - `query` (required): Query string using Yandex Tracker Query Language syntax747 - Returns the total count of issues matching the specified criteria748 - Supports all query language features: field filtering, date functions, logical operators, and complex expressions749 - Useful for analytics, reporting, and understanding issue distribution without retrieving full issue data750751</details>752753## http Transport754755The MCP server can also be run in streamable-http mode for web-based integrations or when stdio transport is not suitable.756757### streamable-http Mode Environment Variables758759```env760# Required - Set transport to streamable-http mode761TRANSPORT=streamable-http762763# Server Configuration764HOST=0.0.0.0 # Default: 0.0.0.0 (all interfaces)765PORT=8000 # Default: 8000766```767768### Starting the streamable-http Server769770```bash771# Basic streamable-http server startup772TRANSPORT=streamable-http uvx yandex-tracker-mcp@latest773774# With custom host and port775TRANSPORT=streamable-http \776HOST=localhost \777PORT=9000 \778uvx yandex-tracker-mcp@latest779780# With all environment variables781TRANSPORT=streamable-http \782HOST=0.0.0.0 \783PORT=8000 \784TRACKER_TOKEN=your_token \785TRACKER_CLOUD_ORG_ID=your_org_id \786uvx yandex-tracker-mcp@latest787```788789You 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):790791```bash792claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?cloudOrgId=your_cloud_org_id&"793```794795or796797```bash798claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?orgId=org_id&"799```800801You may also skip configuring global `TRACKER_TOKEN` environment variable if you choose to use OAuth 2.0 authentication (see below).802803### OAuth 2.0 Authentication804805The 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.806807#### How OAuth Works808809The MCP server implements a standard OAuth 2.0 authorization code flow:8108111. **Client Registration**: Your MCP client registers with the server to obtain client credentials8122. **Authorization**: Users are redirected to Yandex OAuth to authenticate8133. **Token Exchange**: The server exchanges authorization codes for access tokens8144. **API Access**: Clients use bearer tokens for all API requests8155. **Token Refresh**: Expired tokens can be refreshed without re-authentication816817```818MCP Client → MCP Server → Yandex OAuth → User Authentication819 ↑ ↓820 └────────── Access Token ←─────────────────┘821```822823#### OAuth Configuration824825To enable OAuth authentication, set the following environment variables:826827```env828# Enable OAuth mode829OAUTH_ENABLED=true830831# Yandex OAuth Application Credentials (required for OAuth)832OAUTH_CLIENT_ID=your_yandex_oauth_app_id833OAUTH_CLIENT_SECRET=your_yandex_oauth_app_secret834835# Public URL of your MCP server (required for OAuth callbacks)836MCP_SERVER_PUBLIC_URL=https://your-mcp-server.example.com837838# Optional OAuth settings839OAUTH_SERVER_URL=https://oauth.yandex.ru # Default Yandex OAuth server840841# When OAuth is enabled, TRACKER_TOKEN becomes optional842```843844#### Setting Up Yandex OAuth Application8458461. Go to [Yandex OAuth](https://oauth.yandex.ru/) and create a new application8472. Set the callback URL to: `{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback`8483. Request the following permissions:849 - `tracker:read` - Read permissions for Tracker850 - `tracker:write` - Write permissions for Tracker8514. Save your Client ID and Client Secret852853#### OAuth vs Static Token Authentication854855| Feature | OAuth | Static Token |856|------------------|--------------------------------|----------------------------|857| Security | Dynamic tokens with expiration | Long-lived static tokens |858| User Experience | Interactive login flow | One-time configuration |859| Token Management | Automatic refresh | Manual rotation |860| Access Control | Per-user authentication | Shared token |861| Setup Complexity | Requires OAuth app setup | Simple token configuration |862863#### OAuth Mode Limitations864865- Currently, the OAuth mode requires the MCP server to be publicly accessible for callback URLs866- OAuth mode is best suited for interactive clients that support web-based authentication flows867868#### Using OAuth with MCP Clients869870When OAuth is enabled, MCP clients will need to:8711. Support OAuth 2.0 authorization code flow8722. Handle token refresh when access tokens expire8733. Store refresh tokens securely for persistent authentication874875**Note**: Not all MCP clients currently support OAuth authentication. Check your client's documentation for OAuth compatibility.876877Example configuration for Claude Code:878879```bash880claude mcp add --transport http yandex-tracker https://your-mcp-server.example.com/mcp/ -s user881```882883#### OAuth Data Storage884885The MCP server supports two different storage backends for OAuth data (client registrations, access tokens, refresh tokens, and authorization states):886887##### InMemory Store (Default)888889The in-memory store keeps all OAuth data in server memory. This is the default option and requires no additional configuration.890891**Characteristics:**892- **Persistence**: Data is lost when the server restarts893- **Performance**: Very fast access since data is stored in memory894- **Scalability**: Limited to single server instance895- **Setup**: No additional dependencies required896- **Best for**: Development, testing, or single-instance deployments where losing OAuth sessions on restart is acceptable897898**Configuration:**899```env900OAUTH_STORE=memory # Default value, can be omitted901```902903##### Redis Store904905The Redis store provides persistent storage for OAuth data using a Redis database. This ensures OAuth sessions survive server restarts and enables multi-instance deployments.906907**Characteristics:**908- **Persistence**: Data persists across server restarts909- **Performance**: Fast access with network overhead910- **Scalability**: Supports multiple server instances sharing the same Redis database911- **Setup**: Requires Redis server installation and configuration912- **Best for**: Production deployments, high availability setups, or when OAuth sessions must persist913914**Configuration:**915```env916# Enable Redis store for OAuth data917OAUTH_STORE=redis918919# Redis connection settings (same as used for tools caching)920REDIS_ENDPOINT=localhost # Default: localhost921REDIS_PORT=6379 # Default: 6379922REDIS_DB=0 # Default: 0923REDIS_PASSWORD=your_redis_password # Optional: Redis password924REDIS_POOL_MAX_SIZE=10 # Default: 10925```926927**Storage Behavior:**928- **Client Information**: Stored persistently929- **OAuth States**: Stored with TTL (time-to-live) for security930- **Authorization Codes**: Stored with TTL and automatically cleaned up after use931- **Access Tokens**: Stored with automatic expiration based on token lifetime932- **Refresh Tokens**: Stored persistently until revoked933- **Key Namespacing**: Uses `oauth:*` prefixes to avoid conflicts with other Redis data934935##### Token Encryption (Required for Redis Store)936937When using Redis store, you must configure encryption to protect OAuth tokens at rest. Token values are encrypted using Fernet (AES-128) and Redis keys use SHA-256 hashes instead of raw tokens, preventing token exposure if Redis is compromised.938939**Generate an encryption key:**940```bash941python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"942```943944**Configuration:**945```env946# Single encryption key947OAUTH_ENCRYPTION_KEYS=<base64-encoded-32-byte-key>948949# Multiple keys for rotation (first encrypts, all decrypt)950OAUTH_ENCRYPTION_KEYS=<new-key>,<old-key>951```952953Key rotation allows seamless key updates: add the new key first, wait for old tokens to expire, then remove the old key.954955**Important Notes:**956- Both stores use the same Redis connection settings as the tools caching system957- When using Redis store, ensure your Redis instance is properly secured and accessible958- The `OAUTH_STORE` setting only affects OAuth data storage; tools caching uses `TOOLS_CACHE_ENABLED`959- Redis store uses JSON serialization for better cross-language compatibility and debugging960961## Authentication962963Yandex 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:964965### Authentication Priority Order9669671. **Dynamic OAuth Token** (highest priority)968 - When OAuth is enabled and a user authenticates via OAuth flow969 - Tokens are dynamically obtained and refreshed per user session970 - Supports both standard Yandex OAuth and Yandex Cloud federative OAuth971 - Required env vars: `OAUTH_ENABLED=true`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `MCP_SERVER_PUBLIC_URL`972 - Additional vars for federative OAuth: `OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth`, `OAUTH_TOKEN_TYPE=Bearer`, `OAUTH_USE_SCOPES=false`9739742. **Static OAuth Token**975 - Traditional OAuth token provided via environment variable976 - Single token used for all requests977 - Required env var: `TRACKER_TOKEN` (your OAuth token)9789793. **Static IAM Token**980 - IAM (Identity and Access Management) token for service-to-service authentication981 - Suitable for automated systems and CI/CD pipelines982 - Required env var: `TRACKER_IAM_TOKEN` (your IAM token)9839844. **Dynamic IAM Token** (lowest priority)985 - Automatically retrieved using service account credentials986 - Token is fetched and refreshed automatically987 - Required env vars: `TRACKER_SA_KEY_ID`, `TRACKER_SA_SERVICE_ACCOUNT_ID`, `TRACKER_SA_PRIVATE_KEY`988989### Authentication Scenarios990991#### Scenario 1: OAuth with Dynamic Tokens (Recommended for Interactive Use)992```env993# Enable OAuth mode994OAUTH_ENABLED=true995OAUTH_CLIENT_ID=your_oauth_app_id996OAUTH_CLIENT_SECRET=your_oauth_app_secret997MCP_SERVER_PUBLIC_URL=https://your-server.com998999# Organization ID (choose one)1000TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID1001```10021003#### Scenario 2: Static OAuth Token (Simple Setup)1004```env1005# OAuth token1006TRACKER_TOKEN=your_oauth_token10071008# Organization ID (choose one)1009TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID1010```10111012#### Scenario 3: Static IAM Token1013```env1014# IAM token1015TRACKER_IAM_TOKEN=your_iam_token10161017# Organization ID (choose one)1018TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID1019```10201021#### Scenario 4: Dynamic IAM Token with Service Account1022```env1023# Service account credentials1024TRACKER_SA_KEY_ID=your_key_id1025TRACKER_SA_SERVICE_ACCOUNT_ID=your_service_account_id1026TRACKER_SA_PRIVATE_KEY=your_private_key10271028# Organization ID (choose one)1029TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID1030```10311032#### Scenario 5: Federative OAuth for OIDC Applications (Advanced)1033```env1034# Enable OAuth with Yandex Cloud federation1035OAUTH_ENABLED=true1036OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth1037OAUTH_TOKEN_TYPE=Bearer1038OAUTH_USE_SCOPES=false1039OAUTH_CLIENT_ID=your_oidc_client_id1040OAUTH_CLIENT_SECRET=your_oidc_client_secret1041MCP_SERVER_PUBLIC_URL=https://your-server.com10421043# Organization ID (choose one)1044TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID1045```10461047This configuration enables authentication through [Yandex Cloud OIDC applications](https://yandex.cloud/ru/docs/organization/operations/applications/oidc-create), which is required for [federated accounts](https://yandex.cloud/ru/docs/organization/operations/manage-federations) in Yandex Cloud. Federated users authenticate through their organization's identity provider (IdP) and use this OAuth flow to access Yandex Tracker APIs.10481049### Important Notes10501051- The server checks authentication methods in the order listed above1052- Only one authentication method will be used at a time1053- For production use, dynamic tokens (OAuth or IAM) are recommended for better security1054- IAM tokens have a shorter lifetime than OAuth tokens and may need more frequent renewal1055- When using service accounts, ensure the account has appropriate permissions for Yandex Tracker10561057## Configuration10581059### Environment Variables10601061```env1062# Authentication (use one of the following methods)1063# Method 1: OAuth Token1064TRACKER_TOKEN=your_yandex_tracker_oauth_token10651066# Method 2: IAM Token1067TRACKER_IAM_TOKEN=your_iam_token10681069# Method 3: Service Account (for dynamic IAM token)1070TRACKER_SA_KEY_ID=your_key_id # Service account key ID1071TRACKER_SA_SERVICE_ACCOUNT_ID=your_sa_id # Service account ID1072TRACKER_SA_PRIVATE_KEY=your_private_key # Service account private key10731074# Organization Configuration (choose one)1075TRACKER_CLOUD_ORG_ID=your_cloud_org_id # For Yandex Cloud organizations1076TRACKER_ORG_ID=your_org_id # For Yandex 360 organizations10771078# API Configuration (optional)1079TRACKER_API_BASE_URL=https://api.tracker.yandex.net # Default: https://api.tracker.yandex.net10801081# Security - Restrict access to specific queues (optional)1082TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV # Comma-separated queue keys10831084# Server Configuration1085HOST=0.0.0.0 # Default: 0.0.0.01086PORT=8000 # Default: 80001087TRANSPORT=stdio # Options: stdio, streamable-http, sse10881089# Redis connection settings (used for caching and OAuth store)1090REDIS_ENDPOINT=localhost # Default: localhost1091REDIS_PORT=6379 # Default: 63791092REDIS_DB=0 # Default: 01093REDIS_PASSWORD=your_redis_password # Optional: Redis password1094REDIS_POOL_MAX_SIZE=10 # Default: 1010951096# Tools caching configuration (optional)1097TOOLS_CACHE_ENABLED=true # Default: false1098TOOLS_CACHE_REDIS_TTL=3600 # Default: 3600 seconds (1 hour)10991100# OAuth 2.0 Authentication (optional)1101OAUTH_ENABLED=true # Default: false1102OAUTH_STORE=redis # Options: memory, redis (default: memory)1103OAUTH_SERVER_URL=https://oauth.yandex.ru # Default: https://oauth.yandex.ru (use https://auth.yandex.cloud/oauth for federation)1104OAUTH_TOKEN_TYPE=<Bearer|OAuth|<empty>> # Default: <empty> (required to be Bearer for Yandex Cloud federation)1105OAUTH_USE_SCOPES=true # Default: true (set to false for Yandex Cloud federation)1106OAUTH_CLIENT_ID=your_oauth_client_id # Required when OAuth enabled1107OAUTH_CLIENT_SECRET=your_oauth_secret # Required when OAuth enabled1108MCP_SERVER_PUBLIC_URL=https://your.server.com # Required when OAuth enabled1109TRACKER_READ_ONLY=true # Default: false - Limit OAuth to read-only permissions1110```11111112## Docker Deployment11131114### Using Pre-built Image (Recommended)11151116```bash1117# Using environment file1118docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest11191120# With inline environment variables1121docker run -e TRACKER_TOKEN=your_token \1122 -e TRACKER_CLOUD_ORG_ID=your_org_id \1123 -p 8000:8000 \1124 ghcr.io/aikts/yandex-tracker-mcp:latest1125```11261127### Building the Image Locally11281129```bash1130docker build -t yandex-tracker-mcp .1131```11321133### Docker Compose11341135**Using pre-built image:**1136```yaml1137version: '3.8'1138services:1139 mcp-tracker:1140 image: ghcr.io/aikts/yandex-tracker-mcp:latest1141 ports:1142 - "8000:8000"1143 environment:1144 - TRACKER_TOKEN=${TRACKER_TOKEN}1145 - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}1146```11471148**Building locally:**1149```yaml1150version: '3.8'1151services:1152 mcp-tracker:1153 build: .1154 ports:1155 - "8000:8000"1156 environment:1157 - TRACKER_TOKEN=${TRACKER_TOKEN}1158 - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}1159```11601161### Development Setup11621163```bash1164# Clone and setup1165git clone https://github.com/aikts/yandex-tracker-mcp1166cd yandex-tracker-mcp11671168# Install development dependencies1169uv sync --dev11701171# Formatting and static checking1172task1173```11741175## License11761177This project is licensed under the terms specified in the [LICENSE](LICENSE) file.11781179## Support11801181For issues and questions:1182- Review Yandex Tracker API documentation1183- Submit issues at https://github.com/aikts/yandex-tracker-mcp/issues1184
Full transparency — inspect the skill content before installing.