Yandex Tracker Server

Local Model Context Protocol server (Node.js + TypeScript) that exposes the Yandex Tracker REST API v3 as tools for LLM clients. Transport is stdio only (the host spawns the process; there is no HTTP port).

Prerequisites

• Node.js 18+
• A Tracker OAuth token and organisation ID (see below)

Install and run

npm install
npm run build    # compile to dist/
npm run start    # run compiled server (used by MCP hosts)

Other scripts:

Script	Purpose
npm run clean	Remove the dist/ directory
npm run dev	Run src/index.ts with tsx (handy for quick local checks; MCP hosts normally use start)

After clean, run build again before start.

Configuration

1. Copy .env.example to .env and fill in values (do not commit .env).

2. Required variables:

   • TRACKER_TOKEN — OAuth token (see below)
   • TRACKER_ORG_ID — Organisation ID from Tracker administration → Organisations

   Optional:

   • TRACKER_ORG_HEADER — X-Org-ID (Yandex 360, default) or X-Cloud-Org-ID (Yandex Cloud)
   • TRACKER_BASE_URL — default https://api.tracker.yandex.net/v3; change for self-hosted
   • TRACKER_AUTH_SCHEME — OAuth (default) or Bearer (e.g. IAM)

Getting a Tracker OAuth token

1. Create an OAuth app at https://oauth.yandex.ru/ (choose API access / debugging, add scopes tracker:read and tracker:write, note the Client ID).

2. Authorize in the browser (implicit flow). Open (replace YOUR_CLIENT_ID):

   https://oauth.yandex.com/authorize?response_type=token&client_id=YOUR_CLIENT_ID

3. After you approve access, the redirect URL will contain access_token=.... Copy that value into TRACKER_TOKEN.

4. Smoke test (optional):

   curl -sS 'https://api.tracker.yandex.net/v3/myself' \
     -H 'Authorization: OAuth YOUR_TOKEN' \
     -H 'X-Org-ID: YOUR_ORG_ID'
   

   401 usually means a bad token; 403 often means a wrong org header or ID.

Using with Cursor

1. Build the project and note the absolute path to dist/index.js.

2. Edit your MCP config (e.g. ~/.cursor/mcp.json) and add a server entry. Example:

   {
     "mcpServers": {
       "tracker-custom": {
         "command": "node",
         "args": ["/absolute/path/to/tracker-mcp-server/dist/index.js"],
         "env": {
           "TRACKER_TOKEN": "your_oauth_token",
           "TRACKER_ORG_ID": "your_org_id",
           "TRACKER_ORG_HEADER": "X-Org-ID",
           "TRACKER_BASE_URL": "https://api.tracker.yandex.net/v3",
           "TRACKER_AUTH_SCHEME": "OAuth"
         }
       }
     }
   }
   

   You can rely on a .env file only if your host loads it; many setups pass env explicitly as above.

3. Restart Cursor. In chat, try: use the Tracker MCP to call get_myself to verify auth.

Using with Claude Desktop

1. Build the project and note the absolute path to dist/index.js.

2. Edit the Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Under mcpServers, add the same shape as in the Cursor example (command, args, env).

4. Fully quit and reopen Claude Desktop, then use a task that invokes Tracker tools (e.g. get_myself).

Project layout (high level)

• src/index.ts — MCP entry, registers tools, stdio transport
• src/tracker-client.ts — HTTP client for Tracker API
• src/tools/*.ts — tool implementations (read, write, validate, checklist, sync)
• convention.json — validation rules for validate_issue / audit_queue
• sync-map.json — optional Tracker ↔ Miro id map for agent-driven sync

License

Private / use as you prefer unless you add a formal license file.