Skip to content
Back to search

yandex-tracker-mcp

Yandex Tracker MCP Server with OAuth2 support

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aikts--yandex-tracker-mcp/badge.svg)](/listings/aikts--yandex-tracker-mcp)

HTML

<a href="/listings/aikts--yandex-tracker-mcp"><img src="/api/listings/aikts--yandex-tracker-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Yandex Tracker MCP Server can be one-click installed in Claude Desktop as and [extension](https://www.anthropic.com/engineering/desktop-extensions).

Installation

1. Download the `*.mcpb` file from [GitHub Releases](https://github.com/aikts/yandex-tracker-mcp/releases/latest). 2. Double-click the downloaded file to install it in Claude Desktop. ![img.png](images/claude-desktop-install.png) 3. Provide your Yandex Tracker OAuth token when prompted. ![img.png](images/claude-desktop-config.png) 4. Make sure extension is enabled - now you may use this MCP Server.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,163 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Yandex Tracker MCP Server
  2. ![PyPI - Version](https://img.shields.io/pypi/v/yandex-tracker-mcp)
  3. ![Test Workflow](https://github.com/aikts/yandex-tracker-mcp/actions/workflows/test.yml/badge.svg?branch=main)
  4. ![Release Workflow](https://github.com/aikts/yandex-tracker-mcp/actions/workflows/release.yml/badge.svg?branch=main)
  5. mcp-name: io.github.aikts/yandex-tracker-mcp
  6. 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.
  7. <a href="https://glama.ai/mcp/servers/@aikts/yandex-tracker-mcp">
  8. <img width="380" height="200" src="https://glama.ai/mcp/servers/@aikts/yandex-tracker-mcp/badge" />
  9. </a>
  10. Documentation in Russian is available [here](README_ru.md) / Документация на русском языке доступна [здесь](README_ru.md).
  11. ## Features
  12. - **Complete Queue Management**: List and access all available Yandex Tracker queues with pagination support, tag retrieval, and detailed metadata
  13. - **Projects, Portfolios and Goals**: Dedicated read and write tools with explicit schemas for each entity type in the Tracker "entities" API (opt-in via `TRACKER_ENTITIES_ENABLED`)
  14. - **User Management**: Retrieve user account information, including login details, email addresses, license status, and organizational data
  15. - **Full Issue Lifecycle**: Create, read, update, and manage issues with support for custom fields, attachments, and workflow transitions
  16. - **Status Workflow Management**: Execute status transitions, close issues with resolutions, and navigate complex workflows
  17. - **Field Management**: Access global fields, queue-specific local fields, statuses, issue types, priorities, and resolutions
  18. - **Boards and Sprints**: List agile boards and their sprints to find sprint IDs for issue planning
  19. - **Advanced Query Language**: Full Yandex Tracker Query Language support with complex filtering, sorting, and date functions
  20. - **Performance Caching**: Optional Redis caching layer for improved response times
  21. - **Security Controls**: Configurable queue access restrictions and secure token handling
  22. - **Multiple Transport Options**: Support for stdio, SSE (deprecated), and HTTP transports for flexible integration
  23. - **OAuth 2.0 Authentication**: Dynamic token-based authentication with automatic refresh support as an alternative to static API tokens
  24. - **Organization Support**: Compatible with both standard and cloud organization IDs
  25. ### Organization ID Configuration
  26. Choose one of the following based on your Yandex organization type:
  27. - **Yandex Cloud Organization**: Use `TRACKER_CLOUD_ORG_ID` env var later for Yandex Cloud-managed organizations
  28. - **Yandex 360 Organization**: Use `TRACKER_ORG_ID` env var later for Yandex 360 organizations
  29. You can find your organization ID in the Yandex Tracker URL or organization settings.
  30. ## MCP Client Configuration
  31. ### Installing extension in Claude Desktop
  32. Yandex Tracker MCP Server can be one-click installed in Claude Desktop as and [extension](https://www.anthropic.com/engineering/desktop-extensions).
  33. #### Installation
  34. 1. Download the `*.mcpb` file from [GitHub Releases](https://github.com/aikts/yandex-tracker-mcp/releases/latest).
  35. 2. Double-click the downloaded file to install it in Claude Desktop. ![img.png](images/claude-desktop-install.png)
  36. 3. Provide your Yandex Tracker OAuth token when prompted. ![img.png](images/claude-desktop-config.png)
  37. 4. Make sure extension is enabled - now you may use this MCP Server.
  38. ### Manual installation
  39. #### Prerequisites
  40. - [uv](https://docs.astral.sh/uv/getting-started/installation/) installed globally
  41. - Valid Yandex Tracker API token with appropriate permissions
  42. 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:
  43. - Authentication (one of the following):
  44. - `TRACKER_TOKEN` - Your Yandex Tracker OAuth token
  45. - `TRACKER_IAM_TOKEN` - Your IAM token
  46. - `TRACKER_SA_KEY_ID`, `TRACKER_SA_SERVICE_ACCOUNT_ID`, `TRACKER_SA_PRIVATE_KEY` - Service account credentials
  47. - Organization - exactly one of the following:
  48. - `TRACKER_CLOUD_ORG_ID` - Your Yandex Cloud organization ID
  49. - `TRACKER_ORG_ID` - Your Yandex 360 organization ID
  50. > Set **one** of the two. Setting both makes every Tracker call fail with
  51. > `Only one of org_id or cloud_org_id should be provided.` The examples below use
  52. > `TRACKER_CLOUD_ORG_ID`; on Yandex 360, replace that key with `TRACKER_ORG_ID`.
  53. <details>
  54. <summary><strong>Claude Desktop</strong></summary>
  55. **Configuration file path:**
  56. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  57. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  58. **Using uvx:**
  59. ```json
  60. {
  61. "mcpServers": {
  62. "yandex-tracker": {
  63. "command": "uvx",
  64. "args": ["yandex-tracker-mcp@latest"],
  65. "env": {
  66. "TRACKER_TOKEN": "your_tracker_token_here",
  67. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. **Using Docker:**
  74. ```json
  75. {
  76. "mcpServers": {
  77. "yandex-tracker": {
  78. "command": "docker",
  79. "args": [
  80. "run", "--rm", "-i",
  81. "-e", "TRACKER_TOKEN",
  82. "-e", "TRACKER_CLOUD_ORG_ID",
  83. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  84. ],
  85. "env": {
  86. "TRACKER_TOKEN": "your_tracker_token_here",
  87. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  88. }
  89. }
  90. }
  91. }
  92. ```
  93. </details>
  94. <details>
  95. <summary><strong>Claude Code</strong></summary>
  96. **Using uvx:**
  97. ```bash
  98. claude mcp add yandex-tracker uvx yandex-tracker-mcp@latest \
  99. -e TRACKER_TOKEN=your_tracker_token_here \
  100. -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here \
  101. -e TRANSPORT=stdio
  102. ```
  103. **Using Docker:**
  104. ```bash
  105. claude 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 TRANSPORT=stdio ghcr.io/aikts/yandex-tracker-mcp:latest"
  106. ```
  107. </details>
  108. <details>
  109. <summary><strong>Cursor</strong></summary>
  110. **Configuration file path:**
  111. - Project-specific: `.cursor/mcp.json` in your project directory
  112. - Global: `~/.cursor/mcp.json`
  113. **Using uvx:**
  114. ```json
  115. {
  116. "mcpServers": {
  117. "yandex-tracker": {
  118. "command": "uvx",
  119. "args": ["yandex-tracker-mcp@latest"],
  120. "env": {
  121. "TRACKER_TOKEN": "your_tracker_token_here",
  122. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  123. }
  124. }
  125. }
  126. }
  127. ```
  128. **Using Docker:**
  129. ```json
  130. {
  131. "mcpServers": {
  132. "yandex-tracker": {
  133. "command": "docker",
  134. "args": [
  135. "run", "--rm", "-i",
  136. "-e", "TRACKER_TOKEN",
  137. "-e", "TRACKER_CLOUD_ORG_ID",
  138. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  139. ],
  140. "env": {
  141. "TRACKER_TOKEN": "your_tracker_token_here",
  142. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  143. }
  144. }
  145. }
  146. }
  147. ```
  148. </details>
  149. <details>
  150. <summary><strong>Windsurf</strong></summary>
  151. **Configuration file path:**
  152. - `~/.codeium/windsurf/mcp_config.json`
  153. Access via: Windsurf Settings → Cascade tab → Model Context Protocol (MCP) Servers → "View raw config"
  154. **Using uvx:**
  155. ```json
  156. {
  157. "mcpServers": {
  158. "yandex-tracker": {
  159. "command": "uvx",
  160. "args": ["yandex-tracker-mcp@latest"],
  161. "env": {
  162. "TRACKER_TOKEN": "your_tracker_token_here",
  163. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  164. }
  165. }
  166. }
  167. }
  168. ```
  169. **Using Docker:**
  170. ```json
  171. {
  172. "mcpServers": {
  173. "yandex-tracker": {
  174. "command": "docker",
  175. "args": [
  176. "run", "--rm", "-i",
  177. "-e", "TRACKER_TOKEN",
  178. "-e", "TRACKER_CLOUD_ORG_ID",
  179. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  180. ],
  181. "env": {
  182. "TRACKER_TOKEN": "your_tracker_token_here",
  183. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  184. }
  185. }
  186. }
  187. }
  188. ```
  189. </details>
  190. <details>
  191. <summary><strong>Zed</strong></summary>
  192. **Configuration file path:**
  193. - `~/.config/zed/settings.json`
  194. Access via: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows) or command palette: "zed: open settings"
  195. **Note:** Requires Zed Preview version for MCP support.
  196. **Using uvx:**
  197. ```json
  198. {
  199. "context_servers": {
  200. "yandex-tracker": {
  201. "source": "custom",
  202. "command": {
  203. "path": "uvx",
  204. "args": ["yandex-tracker-mcp@latest"],
  205. "env": {
  206. "TRACKER_TOKEN": "your_tracker_token_here",
  207. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  208. }
  209. }
  210. }
  211. }
  212. }
  213. ```
  214. **Using Docker:**
  215. ```json
  216. {
  217. "context_servers": {
  218. "yandex-tracker": {
  219. "source": "custom",
  220. "command": {
  221. "path": "docker",
  222. "args": [
  223. "run", "--rm", "-i",
  224. "-e", "TRACKER_TOKEN",
  225. "-e", "TRACKER_CLOUD_ORG_ID",
  226. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  227. ],
  228. "env": {
  229. "TRACKER_TOKEN": "your_tracker_token_here",
  230. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  231. }
  232. }
  233. }
  234. }
  235. }
  236. ```
  237. </details>
  238. <details>
  239. <summary><strong>GitHub Copilot (VS Code)</strong></summary>
  240. **Configuration file path:**
  241. - Workspace: `.vscode/mcp.json` in your project directory
  242. - Global: VS Code `settings.json`
  243. **Option 1: Workspace Configuration (Recommended for security)**
  244. Create `.vscode/mcp.json`:
  245. **Using uvx:**
  246. ```json
  247. {
  248. "inputs": [
  249. {
  250. "type": "promptString",
  251. "id": "tracker-token",
  252. "description": "Yandex Tracker Token",
  253. "password": true
  254. },
  255. {
  256. "type": "promptString",
  257. "id": "cloud-org-id",
  258. "description": "Yandex Cloud Organization ID"
  259. }
  260. ],
  261. "servers": {
  262. "yandex-tracker": {
  263. "type": "stdio",
  264. "command": "uvx",
  265. "args": ["yandex-tracker-mcp@latest"],
  266. "env": {
  267. "TRACKER_TOKEN": "${input:tracker-token}",
  268. "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
  269. "TRANSPORT": "stdio"
  270. }
  271. }
  272. }
  273. }
  274. ```
  275. **Using Docker:**
  276. ```json
  277. {
  278. "inputs": [
  279. {
  280. "type": "promptString",
  281. "id": "tracker-token",
  282. "description": "Yandex Tracker Token",
  283. "password": true
  284. },
  285. {
  286. "type": "promptString",
  287. "id": "cloud-org-id",
  288. "description": "Yandex Cloud Organization ID"
  289. }
  290. ],
  291. "servers": {
  292. "yandex-tracker": {
  293. "type": "stdio",
  294. "command": "docker",
  295. "args": [
  296. "run", "--rm", "-i",
  297. "-e", "TRACKER_TOKEN",
  298. "-e", "TRACKER_CLOUD_ORG_ID",
  299. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  300. ],
  301. "env": {
  302. "TRACKER_TOKEN": "${input:tracker-token}",
  303. "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
  304. "TRANSPORT": "stdio"
  305. }
  306. }
  307. }
  308. }
  309. ```
  310. **Option 2: Global Configuration**
  311. Add to VS Code `settings.json`:
  312. **Using uvx:**
  313. ```json
  314. {
  315. "github.copilot.chat.mcp.servers": {
  316. "yandex-tracker": {
  317. "type": "stdio",
  318. "command": "uvx",
  319. "args": ["yandex-tracker-mcp@latest"],
  320. "env": {
  321. "TRACKER_TOKEN": "your_tracker_token_here",
  322. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  323. }
  324. }
  325. }
  326. }
  327. ```
  328. **Using Docker:**
  329. ```json
  330. {
  331. "github.copilot.chat.mcp.servers": {
  332. "yandex-tracker": {
  333. "type": "stdio",
  334. "command": "docker",
  335. "args": [
  336. "run", "--rm", "-i",
  337. "-e", "TRACKER_TOKEN",
  338. "-e", "TRACKER_CLOUD_ORG_ID",
  339. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  340. ],
  341. "env": {
  342. "TRACKER_TOKEN": "your_tracker_token_here",
  343. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  344. }
  345. }
  346. }
  347. }
  348. ```
  349. </details>
  350. <details>
  351. <summary><strong>Other MCP-Compatible Clients</strong></summary>
  352. For other MCP-compatible clients, use the standard MCP server configuration format:
  353. **Using uvx:**
  354. ```json
  355. {
  356. "mcpServers": {
  357. "yandex-tracker": {
  358. "command": "uvx",
  359. "args": ["yandex-tracker-mcp@latest"],
  360. "env": {
  361. "TRACKER_TOKEN": "your_tracker_token_here",
  362. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  363. }
  364. }
  365. }
  366. }
  367. ```
  368. **Using Docker:**
  369. ```json
  370. {
  371. "mcpServers": {
  372. "yandex-tracker": {
  373. "command": "docker",
  374. "args": [
  375. "run", "--rm", "-i",
  376. "-e", "TRACKER_TOKEN",
  377. "-e", "TRACKER_CLOUD_ORG_ID",
  378. "ghcr.io/aikts/yandex-tracker-mcp:latest"
  379. ],
  380. "env": {
  381. "TRACKER_TOKEN": "your_tracker_token_here",
  382. "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
  383. }
  384. }
  385. }
  386. }
  387. ```
  388. </details>
  389. **Important Notes:**
  390. - Replace placeholder values with your actual credentials
  391. - Restart your AI client after configuration changes
  392. - Ensure `uvx` is installed and available in your system PATH
  393. - For production use, consider using environment variables instead of hardcoding tokens
  394. ## Available MCP Tools
  395. The server exposes the following tools through the MCP protocol:
  396. <details>
  397. <summary><strong>Queue Management</strong></summary>
  398. | Tool | What it does | Key arguments |
  399. | --- | --- | --- |
  400. | `queues_get_all` | Every queue the token may see; returns `{values, hits, pages}` | `fields`, `page` (omit to walk every page), `per_page` |
  401. | `queue_get_tags` | The tags defined in the queue | `queue_id` (a key like `"SOMEPROJECT"`) |
  402. | `queue_get_versions` | The queue's versions, with dates and status | `queue_id` |
  403. | `queue_get_components` | The queue's components as full objects, with lead, auto-assign flag and `version`; `queue_get_metadata` with `expand: ["components"]` gives ids and names only | `queue_id` |
  404. | `queue_create_version` | Create a version in the queue | `queue_id`, `name`, `description`, `start_date`, `due_date` (`YYYY-MM-DD`) |
  405. | `queue_get_fields` | The fields configured on the queue, local ones included; `schema.required` marks the mandatory ones | `queue_id`, `include_local_fields` |
  406. | `queue_get_metadata` | Name, description, default type and priority, plus whatever `expand` asks for | `queue_id`, `expand` (`all`, `projects`, `components`, `versions`, `types`, `team`, `workflows`, `fields`, `issueTypesConfig`) |
  407. - Read `queue_get_fields` before `issue_create`, but it is not the whole registry: system fields such as `parent` or `estimation` are settable without appearing there, and `get_global_fields` lists every field the organization has.
  408. - `queue_get_metadata` with `expand: ["issueTypesConfig"]` is where the resolutions valid for each issue type come from - `issue_close` needs one of them.
  409. - All of these respect `TRACKER_LIMIT_QUEUES`. `hits` / `pages` from `queues_get_all` are reported only for an explicit single page on a server without the allow-list, since the totals count queues the allow-list then hides.
  410. </details>
  411. <details>
  412. <summary><strong>Components</strong></summary>
  413. A component is a label grouping a queue's issues by product, process or owner. Its numeric id is what `issue_create` / `issue_update` take in `components`.
  414. | Tool | What it does | Key arguments |
  415. | --- | --- | --- |
  416. | `component_get` | One component with `queue`, `lead`, `assignAuto` and `version` | `component_id` (from `queue_get_components` or an issue's `components`) |
  417. | `component_create` | Create a component in a queue | `queue_id`, `name`, `description`, `lead` (a login or uid), `assign_auto` |
  418. | `component_update` | Change name, description, lead or auto-assign flag; omitted fields keep their value, `clear_lead` removes the lead | `component_id`, `name`, `description`, `lead`, `assign_auto`, `clear_lead`, `version` |
  419. | `component_delete` | Delete a component | `component_id` |
  420. - `TRACKER_LIMIT_QUEUES` and `TRACKER_READ_ONLY_QUEUES` apply through the component's queue: `component_update` and `component_delete` read the component first to learn it, and a component in a queue outside `TRACKER_LIMIT_QUEUES` is reported as not found.
  421. </details>
  422. <details>
  423. <summary><strong>Projects, Portfolios and Goals</strong></summary>
  424. Projects, portfolios and goals are separate Yandex Tracker entities (distinct from queues), exposed through the Tracker "entities" API. Custom (organization-defined) attributes are not modeled and are not returned.
  425. > **These tools are opt-in.** They are registered only when `TRACKER_ENTITIES_ENABLED=true` (default `false`), because they add a large tool manifest and are not covered by the queue restrictions — see [Queue Access Control](#queue-access-control).
  426. The three entity types share one tool set, so it is listed once - the row says what the
  427. tool does, the columns which name to call:
  428. | What it does | Projects | Portfolios | Goals |
  429. | --- | --- | --- | --- |
  430. | One entity by id or shortId | `project_get` | `portfolio_get` | `goal_get` |
  431. | Search by name substring and/or field filters; returns `{values, hits, pages}` | `project_find` | `portfolio_find` | `goal_find` |
  432. | A page of comments; returns `{comments, next_cursor}` | `project_get_comments` | `portfolio_get_comments` | `goal_get_comments` |
  433. | Create, returning the entity | `project_create` | `portfolio_create` | `goal_create` |
  434. | Change any field creation takes | `project_update` | `portfolio_update` | `goal_update` |
  435. | Delete it, and with `with_board` its board too - goals have no board | `project_delete` | `portfolio_delete` | `goal_delete` |
  436. | Add a comment | `project_add_comment` | `portfolio_add_comment` | `goal_add_comment` |
  437. | Edit a comment | `project_update_comment` | `portfolio_update_comment` | `goal_update_comment` |
  438. | Delete a comment | `project_delete_comment` | `portfolio_delete_comment` | `goal_delete_comment` |
  439. | Append one checklist item | `project_add_checklist_item` | `portfolio_add_checklist_item` | - |
  440. | Edit one checklist item, leaving the fields you omit as they are | `project_update_checklist_item` | `portfolio_update_checklist_item` | - |
  441. | Move a checklist item before another one | `project_move_checklist_item` | `portfolio_move_checklist_item` | - |
  442. | Delete one checklist item | `project_delete_checklist_item` | `portfolio_delete_checklist_item` | - |
  443. | Edit several existing items by id | `project_update_checklist` | `portfolio_update_checklist` | - |
  444. | Delete the whole checklist | `project_delete_checklist` | `portfolio_delete_checklist` | - |
  445. - **Arguments.** Reads take `entity_id` and `fields`; the `*_find` tools take `input`, `filter`, `order_by`, `order_asc`, `root_only`, `page`, `per_page`. Create and update take `summary` (required on create), `description`, `lead`, `team_users`, `clients`, `followers`, `start` (goals have none), `end`, `tags`, `entity_status`, `parent_entity`, `team_access` and `links`, and update also `comment` and `version` (optimistic locking). Every tool takes the same `fields` selector and returns the entity.
  446. - **`links` are added, never replaced**, and the API never returns them: an existing link cannot be read back or removed through this server, and a links-only update is rejected rather than reported as a success Tracker silently ignores.
  447. - **Not in the default field set:** `checklistItems` (the checklist tools return the whole entity, so ask for them to see the result), `metricItems`, and a goal's `keyResultItems` - the last two are read-only. Goals use their own `entityStatus` values (`draft`, `according_to_plan`, `at_risk`, `blocked`, `achieved`, `partially_achieved`, `not_achieved`, `exceeded`, `cancelled`). Bulk changes are not supported.
  448. </details>
  449. <details>
  450. <summary><strong>User Management</strong></summary>
  451. | Tool | What it does | Key arguments |
  452. | --- | --- | --- |
  453. | `users_get_all` | A page of the organization's users; returns `{values, hits, pages}` | `page`, `per_page`, `fields` |
  454. | `user_get` | One user by login or uid | `user_id` (`"john.doe"` or `"12345"`) |
  455. | `user_get_current` | The user the current token belongs to | - |
  456. | `users_search` | Find users by login, email or real name | `login_or_email_or_name` |
  457. - `users_search` matches login and email exactly first and falls back to fuzzy name matching (80% similarity, at most the three best matches).
  458. - The page from `users_get_all` is the last one when `page` equals `pages`.
  459. </details>
  460. <details>
  461. <summary><strong>Field Management</strong></summary>
  462. | Tool | What it does | Key arguments |
  463. | --- | --- | --- |
  464. | `get_global_fields` | Every global field of the organization, with its schema and type | - |
  465. Queue-local fields are not here - `queue_get_fields` returns them together with the global ones.
  466. </details>
  467. <details>
  468. <summary><strong>Status and Type Management</strong></summary>
  469. | Tool | What it does | Key arguments |
  470. | --- | --- | --- |
  471. | `get_statuses` | Every issue status the organization defines | - |
  472. | `get_issue_types` | Every issue type, for the `type` argument of `issue_create` / `issue_update` | - |
  473. | `get_priorities` | Every priority, with `id`, `key`, `name` and `order` | - |
  474. | `get_resolutions` | Every resolution, for the `resolution_id` of `issue_close` | - |
  475. These four are organization-wide. A queue may accept only some of the values they list, and Tracker answers 422 for one it does not accept - `queue_get_metadata` with `expand: ["issueTypesConfig"]` says which resolutions each issue type takes.
  476. </details>
  477. <details>
  478. <summary><strong>Templates</strong></summary>
  479. | Tool | What it does | Key arguments |
  480. | --- | --- | --- |
  481. | `issue_templates_get_all` | The issue templates, with the `fieldTemplates` values they prefill; returns `{values, hits, pages}` | `queue`, `page` (omit to walk every page), `per_page` |
  482. | `issue_template_get` | One issue template by id | `template_id` |
  483. | `comment_templates_get_all` | The comment templates, with the `template` text and its `summonees` / `maillistSummonees` | `queue`, `page`, `per_page` |
  484. | `comment_template_get` | One comment template by id | `template_id` |
  485. - **Templates are read-only helpers.** The API cannot create an issue or a comment *from* a template, so `issue_create` and `issue_add_comment` take no `template_id`: read the template and pass its values as the write tool's own arguments. Macros such as `{{today}}` arrive literally.
  486. - The issue body a template prefills is in `fieldTemplates.description`; the template's own `description` describes the template.
  487. - `queue` returns that queue's templates plus the ones bound to no queue, which are usable everywhere. `TRACKER_LIMIT_QUEUES` applies: templates of a restricted queue are omitted from the listings and rejected on direct access, while templates without a queue stay visible.
  488. </details>
  489. <details>
  490. <summary><strong>Boards and Sprints</strong></summary>
  491. | Tool | What it does | Key arguments |
  492. | --- | --- | --- |
  493. | `boards_get_all` | The organization's agile boards; returns `{boards, next_cursor}` | `queue`, `fields`, `cursor` (the previous `next_cursor`), `per_page` |
  494. | `board_get` | One board with `autoFilterSettings` (what it collects), `estimateBy`, `useRanking` and its working `calendar` | `board_id`, `fields` |
  495. | `board_get_columns` | The board's columns with the issue statuses that land in each | `board_id` |
  496. | `board_get_sprints` | The board's sprints with status (`draft`, `in_progress`, `released`, `archived`) and planned/actual dates | `board_id`, `fields` |
  497. - A board has no queue of its own, so `queue` is matched against the board's own filter and misses the boards that filter by something else - a personal board filtering by assignee, for one. To catch those, read a few issues of the queue with `issues_find` and look at their `boards` field.
  498. - Boards belong to the organization, not to a queue, so `TRACKER_LIMIT_QUEUES` does not filter them: only the `queue` argument of `boards_get_all` is checked, and what these tools return can name restricted queues.
  499. - A non-scrum board has no sprints and `board_get_sprints` is rejected for it. The sprint `id` it returns is what `issue_create` / `issue_update` take.
  500. </details>
  501. <details>
  502. <summary><strong>Issue Operations</strong></summary>
  503. | Tool | What it does | Key arguments |
  504. | --- | --- | --- |
  505. | `issue_get` | One issue by key: the full record, the current `version` included | `issue_id`, `include_description` |
  506. | `issue_get_url` | The web URL of an issue | `issue_id` |
  507. | `issue_get_comments` | A page of comments, oldest first; returns `{comments, next_cursor}` | `issue_id`, `cursor`, `per_page`, `fields` |
  508. | `issue_add_comment` | Add a comment; `summonees` is what notifies a user, an `@login` in the text notifies nobody | `issue_id`, `text`, `summonees`, `maillist_summonees`, `markup_type`, `is_add_to_followers` |
  509. | `issue_update_comment` | Edit a comment | `issue_id`, `comment_id`, `text`, `summonees`, `maillist_summonees` |
  510. | `issue_delete_comment` | Delete a comment | `issue_id`, `comment_id` |
  511. | `issue_get_links` | Links to related, blocking and duplicate issues | `issue_id` |
  512. | `issue_add_link` | Link two issues | `issue_id`, `relationship`, `issue` |
  513. | `issue_delete_link` | Remove a link | `issue_id`, `link_id` (from `issue_get_links`) |
  514. | `issue_get_worklogs` | The time logged on one or more issues | `issue_ids`, `fields` |
  515. | `issue_add_worklog` | Log spent time | `issue_id`, `duration` (ISO-8601, `PT1H30M`), `comment`, `start` |
  516. | `issue_update_worklog` | Edit a worklog entry | `issue_id`, `worklog_id`, `duration`, `comment`, `start` |
  517. | `issue_delete_worklog` | Delete a worklog entry | `issue_id`, `worklog_id` |
  518. | `issue_get_attachments` | Attachment metadata | `issue_id`, `fields` |
  519. | `issue_get_checklist` | The checklist, with the item ids the write tools need | `issue_id` |
  520. | `issue_add_checklist_items` | Append items in order, creating the checklist if there is none | `issue_id`, `items` (`text`, `checked`, `assignee`, `deadline`) |
  521. | `issue_update_checklist_item` | Change one item; the fields you omit keep their value | `issue_id`, `checklist_item_id`, `text`, `checked`, `assignee`, `deadline`, `clear_assignee`, `clear_deadline` |
  522. | `issue_delete_checklist_item` | Delete one item | `issue_id`, `checklist_item_id` |
  523. | `issue_get_transitions` | The status transitions available right now, with their ids | `issue_id` |
  524. | `issue_execute_transition` | Run a transition, returning the transitions available afterwards | `issue_id`, `transition_id`, `comment`, `fields` |
  525. | `issue_close` | Find a transition to a done status and run it with a resolution | `issue_id`, `resolution_id`, `comment`, `fields` |
  526. | `issue_get_changelog` | Field edits, status transitions, comment changes and fired triggers; returns `{entries, next_cursor}` | `issue_id`, `cursor`, `per_page`, `field`, `type` |
  527. | `issue_create` | Create an issue, returning it | `queue`, `summary`, `type`, `description`, `markup_type`, `assignee`, `priority`, `parent`, `sprint`, `followers`, `components`, `tags`, `project`, `fields` |
  528. | `issue_update` | Change any of those fields; the ones you omit stay as they are | `issue_id`, `version`, and the arguments `issue_create` takes |
  529. | `issue_move` | Move an issue to another queue, which changes its key (`TASKS-1` → `NEWQUEUE-42`) | `issue_id`, `queue`, `notify`, `notify_author`, `move_all_fields`, `initial_status` |
  530. - **`version` goes stale on its own.** Queue triggers and automation run right after `issue_create` and bump it, so the version it returns is routinely already old. Re-read it with `issue_get` immediately before `issue_update`, or omit it to update the latest version unconditionally; a stale one fails with an editing conflict.
  531. - **Reference fields take the same values on create and on update:** an object with `id` and/or `key`, or - for `type`, `priority` and `parent` - the bare key or id. `components` take `{"id": ...}` or `{"name": ...}`, and `components` / `followers` replace the current list rather than adding to it. Anything without a dedicated argument goes into the `fields` map, keyed by the field `id` from `queue_get_fields`; an entry there overrides the dedicated argument, and an explicit `null` clears the field.
  532. - **Transitions are not guessed.** `issue_execute_transition` only takes ids from `issue_get_transitions`, and before `issue_close` read the issue's `type` with `issue_get` and the resolutions valid for that type from `queue_get_metadata` with `expand: ["issueTypesConfig"]` - each type has its own set. Where the client supports elicitation, `issue_move` asks the user to confirm its flags first, and declining aborts the move.
  533. Every tool here respects `TRACKER_LIMIT_QUEUES` and `TRACKER_READ_ONLY_QUEUES`; the ones that write are registered only when `TRACKER_READ_ONLY` is off.
  534. </details>
  535. <details>
  536. <summary><strong>Search and Discovery</strong></summary>
  537. | Tool | What it does | Key arguments |
  538. | --- | --- | --- |
  539. | `issues_find` | Search issues with [Yandex Tracker Query Language](https://yandex.ru/support/tracker/ru/user/query-filter); returns `{values, hits, pages}` | `query`, `fields`, `include_description`, `page`, `per_page` |
  540. | `issues_count` | How many issues match a query; returns `{"count": N}` | `query` |
  541. - `fields` uses Tracker's own spelling (`storyPoints`, not `story_points`) and accepts any field name, a queue's local and the organization's custom fields included - pass the field `id` from `queue_get_fields`. A name Tracker does not know is dropped silently.
  542. - `include_description` is ignored when `description` is listed in `fields`: naming it there is an explicit request for it.
  543. - `per_page` defaults to 100 and can be lowered when a page does not fit the context window.
  544. </details>
  545. ## http Transport
  546. The MCP server can also be run in streamable-http mode for web-based integrations or when stdio transport is not suitable.
  547. ### streamable-http Mode Environment Variables
  548. ```env
  549. # Required - Set transport to streamable-http mode
  550. TRANSPORT=streamable-http
  551. # Server Configuration
  552. HOST=0.0.0.0 # Default: 0.0.0.0 (all interfaces)
  553. PORT=8000 # Default: 8000
  554. ```
  555. ### Starting the streamable-http Server
  556. ```bash
  557. # Basic streamable-http server startup
  558. TRANSPORT=streamable-http uvx yandex-tracker-mcp@latest
  559. # With custom host and port
  560. TRANSPORT=streamable-http \
  561. HOST=localhost \
  562. PORT=9000 \
  563. uvx yandex-tracker-mcp@latest
  564. # With all environment variables
  565. TRANSPORT=streamable-http \
  566. HOST=0.0.0.0 \
  567. PORT=8000 \
  568. TRACKER_TOKEN=your_token \
  569. TRACKER_CLOUD_ORG_ID=your_org_id \
  570. uvx yandex-tracker-mcp@latest
  571. ```
  572. 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):
  573. ```bash
  574. claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?cloudOrgId=your_cloud_org_id&"
  575. ```
  576. or
  577. ```bash
  578. claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?orgId=org_id&"
  579. ```
  580. You may also skip configuring global `TRACKER_TOKEN` environment variable if you choose to use OAuth 2.0 authentication (see below).
  581. ### OAuth 2.0 Authentication
  582. 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.
  583. #### How OAuth Works
  584. The MCP server implements a standard OAuth 2.0 authorization code flow:
  585. 1. **Client Registration**: Your MCP client registers with the server to obtain client credentials
  586. 2. **Authorization**: Users are redirected to Yandex OAuth to authenticate
  587. 3. **Token Exchange**: The server exchanges authorization codes for access tokens
  588. 4. **API Access**: Clients use bearer tokens for all API requests
  589. 5. **Token Refresh**: Expired tokens can be refreshed without re-authentication
  590. ```
  591. MCP Client → MCP Server → Yandex OAuth → User Authentication
  592. ↑ ↓
  593. └────────── Access Token ←─────────────────┘
  594. ```
  595. #### OAuth Configuration
  596. To enable OAuth authentication, set the following environment variables:
  597. ```env
  598. # Enable OAuth mode
  599. OAUTH_ENABLED=true
  600. # Yandex OAuth Application Credentials (required for OAuth)
  601. OAUTH_CLIENT_ID=your_yandex_oauth_app_id
  602. OAUTH_CLIENT_SECRET=your_yandex_oauth_app_secret
  603. # Public URL of your MCP server (required for OAuth callbacks)
  604. MCP_SERVER_PUBLIC_URL=https://your-mcp-server.example.com
  605. # Optional OAuth settings
  606. OAUTH_SERVER_URL=https://oauth.yandex.ru # Default Yandex OAuth server
  607. # When OAuth is enabled, TRACKER_TOKEN becomes optional
  608. ```
  609. ##### OAuth Scopes
  610. With `OAUTH_USE_SCOPES=true` (the default) the server requests, advertises and requires the Yandex
  611. Tracker scopes `tracker:read` and `tracker:write` - or `tracker:read` alone when
  612. `TRACKER_READ_ONLY=true`, so a read-only instance never asks the user for write access. Setting
  613. `OAUTH_USE_SCOPES=false` drops scopes from the flow entirely, which is what Yandex Cloud federation
  614. requires.
  615. #### Setting Up Yandex OAuth Application
  616. 1. Go to [Yandex OAuth](https://oauth.yandex.ru/) and create a new application
  617. 2. Set the callback URL to: `{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback`
  618. 3. Request the following permissions:
  619. - `tracker:read` - Read permissions for Tracker
  620. - `tracker:write` - Write permissions for Tracker
  621. 4. Save your Client ID and Client Secret
  622. #### OAuth vs Static Token Authentication
  623. | Feature | OAuth | Static Token |
  624. |------------------|--------------------------------|----------------------------|
  625. | Security | Dynamic tokens with expiration | Long-lived static tokens |
  626. | User Experience | Interactive login flow | One-time configuration |
  627. | Token Management | Automatic refresh | Manual rotation |
  628. | Access Control | Per-user authentication | Shared token |
  629. | Setup Complexity | Requires OAuth app setup | Simple token configuration |
  630. #### OAuth Mode Limitations
  631. - Currently, the OAuth mode requires the MCP server to be publicly accessible for callback URLs
  632. - OAuth mode is best suited for interactive clients that support web-based authentication flows
  633. #### Using OAuth with MCP Clients
  634. When OAuth is enabled, MCP clients will need to:
  635. 1. Support OAuth 2.0 authorization code flow
  636. 2. Handle token refresh when access tokens expire
  637. 3. Store refresh tokens securely for persistent authentication
  638. **Note**: Not all MCP clients currently support OAuth authentication. Check your client's documentation for OAuth compatibility.
  639. Example configuration for Claude Code:
  640. ```bash
  641. claude mcp add --transport http yandex-tracker https://your-mcp-server.example.com/mcp/ -s user
  642. ```
  643. #### OAuth Data Storage
  644. The MCP server supports two different storage backends for OAuth data (client registrations, access tokens, refresh tokens, and authorization states):
  645. ##### InMemory Store (Default)
  646. The in-memory store keeps all OAuth data in server memory. This is the default option and requires no additional configuration.
  647. **Characteristics:**
  648. - **Persistence**: Data is lost when the server restarts
  649. - **Performance**: Very fast access since data is stored in memory
  650. - **Scalability**: Limited to single server instance
  651. - **Setup**: No additional dependencies required
  652. - **Best for**: Development, testing, or single-instance deployments where losing OAuth sessions on restart is acceptable
  653. **Configuration:**
  654. ```env
  655. OAUTH_STORE=memory # Default value, can be omitted
  656. ```
  657. ##### Redis Store
  658. 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.
  659. **Characteristics:**
  660. - **Persistence**: Data persists across server restarts
  661. - **Performance**: Fast access with network overhead
  662. - **Scalability**: Supports multiple server instances sharing the same Redis database
  663. - **Setup**: Requires Redis server installation and configuration
  664. - **Best for**: Production deployments, high availability setups, or when OAuth sessions must persist
  665. **Configuration:**
  666. ```env
  667. # Enable Redis store for OAuth data
  668. OAUTH_STORE=redis
  669. # Redis connection settings (same as used for tools caching)
  670. REDIS_ENDPOINT=localhost # Default: localhost
  671. REDIS_PORT=6379 # Default: 6379
  672. REDIS_DB=0 # Default: 0
  673. REDIS_PASSWORD=your_redis_password # Optional: Redis password
  674. REDIS_POOL_MAX_SIZE=10 # Default: 10
  675. ```
  676. **Storage Behavior:**
  677. - **Client Information**: Stored persistently
  678. - **OAuth States**: Stored with TTL (time-to-live) for security
  679. - **Authorization Codes**: Stored with TTL and automatically cleaned up after use
  680. - **Access Tokens**: Stored with automatic expiration based on token lifetime
  681. - **Refresh Tokens**: Stored persistently until revoked
  682. - **Key Namespacing**: Uses `oauth:*` prefixes to avoid conflicts with other Redis data
  683. ##### Token Encryption (Required for Redis Store)
  684. When 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.
  685. **Generate an encryption key:**
  686. ```bash
  687. python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"
  688. ```
  689. **Configuration:**
  690. ```env
  691. # Single encryption key
  692. OAUTH_ENCRYPTION_KEYS=<base64-encoded-32-byte-key>
  693. # Multiple keys for rotation (first encrypts, all decrypt)
  694. OAUTH_ENCRYPTION_KEYS=<new-key>,<old-key>
  695. ```
  696. Key rotation allows seamless key updates: add the new key first, wait for old tokens to expire, then remove the old key.
  697. **Important Notes:**
  698. - Both stores use the same Redis connection settings as the tools caching system
  699. - When using Redis store, ensure your Redis instance is properly secured and accessible
  700. - The `OAUTH_STORE` setting only affects OAuth data storage; tools caching uses `TOOLS_CACHE_ENABLED`
  701. - Redis store uses JSON serialization for better cross-language compatibility and debugging
  702. ## Authentication
  703. 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:
  704. ### Authentication Priority Order
  705. 1. **Dynamic OAuth Token** (highest priority)
  706. - When OAuth is enabled and a user authenticates via OAuth flow
  707. - Tokens are dynamically obtained and refreshed per user session
  708. - Supports both standard Yandex OAuth and Yandex Cloud federative OAuth
  709. - Required env vars: `OAUTH_ENABLED=true`, `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `MCP_SERVER_PUBLIC_URL`
  710. - Additional vars for federative OAuth: `OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth`, `OAUTH_TOKEN_TYPE=Bearer`, `OAUTH_USE_SCOPES=false`
  711. 2. **Passthrough Bearer OAuth Token**
  712. - When MCP OAuth middleware does not provide a token, the server can read a Yandex OAuth token from the incoming `Authorization: Bearer <token>` header
  713. - Useful behind a trusted reverse proxy or gateway that authenticates users, resolves their stored Yandex OAuth token, and injects it per request
  714. - The token from MCP OAuth still has priority when OAuth mode is enabled and active
  715. 3. **Static OAuth Token**
  716. - Traditional OAuth token provided via environment variable
  717. - Single token used for all requests
  718. - Required env var: `TRACKER_TOKEN` (your OAuth token)
  719. 4. **Static IAM Token**
  720. - IAM (Identity and Access Management) token for service-to-service authentication
  721. - Suitable for automated systems and CI/CD pipelines
  722. - Required env var: `TRACKER_IAM_TOKEN` (your IAM token)
  723. 5. **Dynamic IAM Token** (lowest priority)
  724. - Automatically retrieved using service account credentials
  725. - Token is fetched and refreshed automatically
  726. - Required env vars: `TRACKER_SA_KEY_ID`, `TRACKER_SA_SERVICE_ACCOUNT_ID`, `TRACKER_SA_PRIVATE_KEY`
  727. ### Authentication Scenarios
  728. #### Scenario 1: OAuth with Dynamic Tokens (Recommended for Interactive Use)
  729. ```env
  730. # Enable OAuth mode
  731. OAUTH_ENABLED=true
  732. OAUTH_CLIENT_ID=your_oauth_app_id
  733. OAUTH_CLIENT_SECRET=your_oauth_app_secret
  734. MCP_SERVER_PUBLIC_URL=https://your-server.com
  735. # Organization ID (choose one)
  736. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID
  737. ```
  738. #### Scenario 2: Static OAuth Token (Simple Setup)
  739. ```env
  740. # OAuth token
  741. TRACKER_TOKEN=your_oauth_token
  742. # Organization ID (choose one)
  743. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID
  744. ```
  745. #### Scenario 3: Passthrough Bearer Token Behind a Reverse Proxy
  746. Use this mode when a trusted gateway handles user authentication, looks up the user's Yandex OAuth token, and forwards the request to the MCP server with that token in the request header:
  747. ```http
  748. Authorization: Bearer <user_yandex_oauth_token>
  749. ```
  750. ```env
  751. # Organization ID (choose one)
  752. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID
  753. ```
  754. This passthrough token is used only when MCP OAuth middleware has not provided an access token for the request. In OAuth-enabled deployments with an active MCP OAuth session, the MCP OAuth token takes priority.
  755. #### Scenario 4: Static IAM Token
  756. ```env
  757. # IAM token
  758. TRACKER_IAM_TOKEN=your_iam_token
  759. # Organization ID (choose one)
  760. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID
  761. ```
  762. #### Scenario 5: Dynamic IAM Token with Service Account
  763. ```env
  764. # Service account credentials
  765. TRACKER_SA_KEY_ID=your_key_id
  766. TRACKER_SA_SERVICE_ACCOUNT_ID=your_service_account_id
  767. TRACKER_SA_PRIVATE_KEY=your_private_key
  768. # Organization ID (choose one)
  769. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID
  770. ```
  771. #### Scenario 6: Federative OAuth for OIDC Applications (Advanced)
  772. ```env
  773. # Enable OAuth with Yandex Cloud federation
  774. OAUTH_ENABLED=true
  775. OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth
  776. OAUTH_TOKEN_TYPE=Bearer
  777. OAUTH_USE_SCOPES=false
  778. OAUTH_CLIENT_ID=your_oidc_client_id
  779. OAUTH_CLIENT_SECRET=your_oidc_client_secret
  780. MCP_SERVER_PUBLIC_URL=https://your-server.com
  781. # Organization ID (choose one)
  782. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # or TRACKER_ORG_ID
  783. ```
  784. This 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.
  785. ### Important Notes
  786. - The server checks authentication methods in the order listed above
  787. - Only one authentication method will be used at a time
  788. - For production use, dynamic tokens (OAuth or IAM) are recommended for better security
  789. - IAM tokens have a shorter lifetime than OAuth tokens and may need more frequent renewal
  790. - When using service accounts, ensure the account has appropriate permissions for Yandex Tracker
  791. ## Configuration
  792. ### Environment Variables
  793. ```env
  794. # Authentication (use one of the following methods)
  795. # Method 1: OAuth Token
  796. TRACKER_TOKEN=your_yandex_tracker_oauth_token
  797. # Method 2: IAM Token
  798. TRACKER_IAM_TOKEN=your_iam_token
  799. # Method 3: Service Account (for dynamic IAM token)
  800. TRACKER_SA_KEY_ID=your_key_id # Service account key ID
  801. TRACKER_SA_SERVICE_ACCOUNT_ID=your_sa_id # Service account ID
  802. TRACKER_SA_PRIVATE_KEY=your_private_key # Service account private key
  803. # Organization Configuration (set exactly one - setting both is an error)
  804. TRACKER_CLOUD_ORG_ID=your_cloud_org_id # For Yandex Cloud organizations
  805. TRACKER_ORG_ID=your_org_id # For Yandex 360 organizations
  806. # API Configuration (optional)
  807. TRACKER_API_BASE_URL=https://api.tracker.yandex.net # Default: https://api.tracker.yandex.net
  808. TRACKER_API_TIMEOUT=10 # Default: 10 - Per-request timeout in seconds for Tracker API calls
  809. # Security - Restrict access to specific queues (optional)
  810. TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV # Comma-separated queue keys - allow-list of accessible queues
  811. TRACKER_READ_ONLY_QUEUES=PROJ2 # Comma-separated queue keys - allowed for reads but reject writes (per-queue read-only)
  812. TRACKER_ENTITIES_ENABLED=true # Default: false - Register project/portfolio/goal tools (NOT covered by the queue restrictions above)
  813. # Server Configuration
  814. HOST=0.0.0.0 # Default: 0.0.0.0
  815. PORT=8000 # Default: 8000
  816. TRANSPORT=stdio # Options: stdio, streamable-http, sse
  817. # Redis connection settings (used for caching and OAuth store)
  818. REDIS_ENDPOINT=localhost # Default: localhost
  819. REDIS_PORT=6379 # Default: 6379
  820. REDIS_DB=0 # Default: 0
  821. REDIS_PASSWORD=your_redis_password # Optional: Redis password
  822. REDIS_POOL_MAX_SIZE=10 # Default: 10
  823. # Tools caching configuration (optional)
  824. TOOLS_CACHE_ENABLED=true # Default: false
  825. TOOLS_CACHE_REDIS_TTL=3600 # Default: 3600 seconds (1 hour)
  826. # OAuth 2.0 Authentication (optional)
  827. OAUTH_ENABLED=true # Default: false
  828. OAUTH_STORE=redis # Options: memory, redis (default: memory)
  829. OAUTH_SERVER_URL=https://oauth.yandex.ru # Default: https://oauth.yandex.ru (use https://auth.yandex.cloud/oauth for federation)
  830. OAUTH_TOKEN_TYPE=<Bearer|OAuth|<empty>> # Default: <empty> (required to be Bearer for Yandex Cloud federation)
  831. OAUTH_USE_SCOPES=true # Default: true (set to false for Yandex Cloud federation)
  832. OAUTH_CLIENT_ID=your_oauth_client_id # Required when OAuth enabled
  833. OAUTH_CLIENT_SECRET=your_oauth_secret # Required when OAuth enabled
  834. MCP_SERVER_PUBLIC_URL=https://your.server.com # Required when OAuth enabled
  835. TRACKER_READ_ONLY=true # Default: false - Disable all write tools for the whole instance
  836. ```
  837. ### Queue Access Control
  838. Access to queues can be scoped at three levels, from coarse to fine-grained:
  839. - **`TRACKER_LIMIT_QUEUES`** — allow-list of queue keys. Queues outside the list
  840. are treated as *not found / not allowed* for both reads and writes. Keys are
  841. matched ignoring case, here and in `TRACKER_READ_ONLY_QUEUES`, so `dev` and
  842. `DEV` name the same queue. The one exception is the board tools: a board belongs
  843. to the organization rather than to a queue, so they are not filtered and can name
  844. a restricted queue in a board's settings.
  845. - **`TRACKER_READ_ONLY`** — when `true`, all write tools are unregistered, so the
  846. whole instance is read-only.
  847. - **`TRACKER_READ_ONLY_QUEUES`** — per-queue read-only allow-list. Write tools stay
  848. registered, but any mutating call (create/update/move/comment/worklog/link,
  849. queue version creation) targeting a listed queue is rejected, while reads keep
  850. working. Queues not listed here remain read-write.
  851. > **Project/portfolio/goal tools are outside this model.** A project, portfolio or
  852. > goal isn't reliably mappable to a single queue, so none of the three settings
  853. > above constrain them — neither the read tools (`project_get`, `project_find`,
  854. > `*_get_comments`, …) nor the write tools (including comment and checklist
  855. > tools). Enabling them grants org-wide access to those entities for anyone who
  856. > can reach the server. For this reason they are **opt-in**: they are registered
  857. > only when `TRACKER_ENTITIES_ENABLED=true` (default `false`), which also keeps
  858. > the tool manifest small for deployments that don't need them. `TRACKER_READ_ONLY`
  859. > still applies: it unregisters entity write tools along with all other write tools.
  860. This lets a single instance be **read-write on some queues and read-only on
  861. others** at the same time — e.g. `TRACKER_LIMIT_QUEUES=DEV,MGMT` together with
  862. `TRACKER_READ_ONLY_QUEUES=MGMT` gives full access to `DEV` and read-only
  863. visibility into `MGMT`. This is especially useful for a shared MCP gateway where
  864. end users reach Tracker only through the server and never hold the raw token
  865. themselves.
  866. > These checks are in-process guardrails. For clients that hold the raw Tracker
  867. > token directly, real limits should additionally be enforced on the token itself.
  868. ## Docker Deployment
  869. ### Using Pre-built Image (Recommended)
  870. The image defaults to `TRANSPORT=stdio`, which talks over the container's stdin/stdout and
  871. opens no port. Set `TRANSPORT=streamable-http` for the examples below, where the server is
  872. reached over HTTP; for a stdio client, run the container with `-i` and no `-p` instead (see
  873. the [MCP Client Configuration](#mcp-client-configuration) examples).
  874. ```bash
  875. # Using environment file (it must set TRANSPORT=streamable-http)
  876. docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest
  877. # With inline environment variables
  878. docker run -e TRACKER_TOKEN=your_token \
  879. -e TRACKER_CLOUD_ORG_ID=your_org_id \
  880. -e TRANSPORT=streamable-http \
  881. -p 8000:8000 \
  882. ghcr.io/aikts/yandex-tracker-mcp:latest
  883. ```
  884. ### Building the Image Locally
  885. ```bash
  886. docker build -t yandex-tracker-mcp .
  887. ```
  888. ### Docker Compose
  889. **Using pre-built image:**
  890. ```yaml
  891. services:
  892. mcp-tracker:
  893. image: ghcr.io/aikts/yandex-tracker-mcp:latest
  894. ports:
  895. - "8000:8000"
  896. environment:
  897. - TRACKER_TOKEN=${TRACKER_TOKEN}
  898. - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
  899. - TRANSPORT=streamable-http
  900. ```
  901. **Building locally:**
  902. ```yaml
  903. services:
  904. mcp-tracker:
  905. build: .
  906. ports:
  907. - "8000:8000"
  908. environment:
  909. - TRACKER_TOKEN=${TRACKER_TOKEN}
  910. - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
  911. - TRANSPORT=streamable-http
  912. ```
  913. ### Development Setup
  914. ```bash
  915. # Clone and setup
  916. git clone https://github.com/aikts/yandex-tracker-mcp
  917. cd yandex-tracker-mcp
  918. # Install development dependencies
  919. uv sync --dev
  920. # Formatting and static checking
  921. task
  922. ```
  923. ## License
  924. This project is licensed under the terms specified in the [LICENSE](LICENSE) file.
  925. ## Support
  926. For issues and questions:
  927. - Review Yandex Tracker API documentation
  928. - Submit issues at https://github.com/aikts/yandex-tracker-mcp/issues

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.