Yandex Tracker Mcp Server

Yandex Tracker MCP サーバー

mcp-name: io.github.aikts/yandex-tracker-mcp

AI アシスタントが Yandex Tracker API と連携できる、包括的な Model Context Protocol（MCP）サーバーです。このサーバーは、Yandex Tracker の課題、キュー、コメント、作業ログ、検索機能への安全な認証済みアクセスを提供し、パフォーマンス向上のための Redis キャッシュもオプションで利用できます。

ロシア語のドキュメントはこちらでご覧いただけます / Документация на русском языке доступна здесь.

機能

• キュー管理の完全サポート：ページネーション、タグの取得、詳細なメタデータに対応し、利用可能なすべての Yandex Tracker キューを一覧表示してアクセスできます
• プロジェクト、ポートフォリオ、目標：Tracker の「entities」API における各エンティティタイプ専用の読み取り・書き込みツールを、明示的なスキーマとともに提供します（TRACKER_ENTITIES_ENABLED でオプトイン）
• ユーザー管理：ログイン情報、メールアドレス、ライセンスの状態、組織データなど、ユーザーアカウント情報を取得できます
• 課題の全ライフサイクル：カスタムフィールド、添付ファイル、ワークフロー遷移に対応し、課題の作成、読み取り、更新、管理ができます
• ステータスワークフロー管理：ステータス遷移を実行し、解決内容を指定して課題をクローズし、複雑なワークフローを操作できます
• フィールド管理：グローバルフィールド、キュー固有のローカルフィールド、ステータス、課題タイプ、優先度、解決内容にアクセスできます
• ボードとスプリント：アジャイルボードとそのスプリントを一覧表示し、課題計画に必要なスプリント ID を確認できます
• 高度なクエリ言語：複雑なフィルタリング、ソート、日付関数に対応した、Yandex Tracker Query Language の完全なサポート
• パフォーマンスキャッシュ：レスポンス時間を短縮するための Redis キャッシュレイヤーをオプションで利用できます
• セキュリティ制御：キューへのアクセス制限を設定でき、トークンを安全に扱えます
• 複数のトランスポートオプション：柔軟な統合に対応するため、stdio、SSE（非推奨）、HTTP トランスポートをサポートします
• OAuth 2.0 認証：静的 API トークンに代わる選択肢として、自動更新に対応した動的なトークンベース認証を利用できます
• 組織のサポート：標準の組織 ID とクラウド組織 ID の両方に対応します

組織 ID の設定

Yandex の組織タイプに応じて、以下のいずれかを選択してください。

• Yandex Cloud 組織：Yandex Cloud が管理する組織では、後で TRACKER_CLOUD_ORG_ID 環境変数を使用します
• Yandex 360 組織：Yandex 360 組織では、後で TRACKER_ORG_ID 環境変数を使用します

組織 ID は、Yandex Tracker の URL または組織の設定で確認できます。

MCP クライアントの設定

Claude Desktop への拡張機能のインストール

Yandex Tracker MCP Server は、拡張機能として Claude Desktop にワンクリックでインストールできます。

インストール

1. GitHub Releasesから *.mcpb ファイルをダウンロードします。
2. ダウンロードしたファイルをダブルクリックして、Claude Desktop にインストールします。
3. 求められたら、Yandex Tracker の OAuth トークンを入力します。
4. 拡張機能が有効になっていることを確認してください。これで、この MCP サーバーを使用できます。

手動インストール

前提条件

• uv がグローバルにインストールされていること
• 適切な権限を持つ有効な Yandex Tracker API トークン

以下のセクションでは、さまざまな AI クライアント向けに MCP サーバーを設定する方法を説明します。uvx yandex-tracker-mcp@latest または Docker イメージ ghcr.io/aikts/yandex-tracker-mcp:latest のどちらかを使用できます。どちらも次の環境変数が必要です。

• 認証（以下のいずれか）：
  • TRACKER_TOKEN - Yandex Tracker の OAuth トークン
  • TRACKER_IAM_TOKEN - IAM トークン
  • TRACKER_SA_KEY_ID、TRACKER_SA_SERVICE_ACCOUNT_ID、TRACKER_SA_PRIVATE_KEY - サービスアカウントの認証情報
• 組織 - 以下のいずれか1つ：
  • TRACKER_CLOUD_ORG_ID - Yandex Cloud の組織 ID
  • TRACKER_ORG_ID - Yandex 360 の組織 ID

2つのうちいずれか1つを設定してください。両方を設定すると、すべての Tracker 呼び出しが失敗し、 Only one of org_id or cloud_org_id should be provided. と表示されます。以下の例では TRACKER_CLOUD_ORG_ID を使用しています。Yandex 360 を使用する場合は、このキーを TRACKER_ORG_ID に置き換えてください。

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

claude mcp add yandex-tracker uvx yandex-tracker-mcp@latest \
  -e TRACKER_TOKEN=your_tracker_token_here \
  -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here \
  -e TRANSPORT=stdio

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"

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "context_servers": {
    "yandex-tracker": {
      "source": "custom",
      "command": {
        "path": "uvx",
        "args": ["yandex-tracker-mcp@latest"],
        "env": {
          "TRACKER_TOKEN": "your_tracker_token_here",
          "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
        }
      }
    }
  }
}

{
  "context_servers": {
    "yandex-tracker": {
      "source": "custom",
      "command": {
        "path": "docker",
        "args": [
          "run", "--rm", "-i",
          "-e", "TRACKER_TOKEN",
          "-e", "TRACKER_CLOUD_ORG_ID",
          "ghcr.io/aikts/yandex-tracker-mcp:latest"
        ],
        "env": {
          "TRACKER_TOKEN": "your_tracker_token_here",
          "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
        }
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tracker-token",
      "description": "Yandex Tracker Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "cloud-org-id",
      "description": "Yandex Cloud Organization ID"
    }
  ],
  "servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "${input:tracker-token}",
        "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
        "TRANSPORT": "stdio"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tracker-token",
      "description": "Yandex Tracker Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "cloud-org-id",
      "description": "Yandex Cloud Organization ID"
    }
  ],
  "servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "${input:tracker-token}",
        "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
        "TRANSPORT": "stdio"
      }
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

重要な注意事項：

• プレースホルダーの値を実際の認証情報に置き換えてください
• 設定を変更した後は、AI クライアントを再起動してください
• uvx がインストールされ、システムの PATH から利用できることを確認してください
• 本番環境で使用する場合は、トークンをハードコードするのではなく、環境変数を使用することを検討してください

利用可能な MCP ツール

このサーバーは、MCP プロトコルを通じて次のツールを公開します：

HTTP トランスポート

MCP サーバーは、ウェブベースの統合や stdio トランスポートが適さない場合に、streamable-http モードで実行することもできます。

streamable-http モードの環境変数

# Required - Set transport to streamable-http mode
TRANSPORT=streamable-http

# Server Configuration
HOST=0.0.0.0  # Default: 0.0.0.0 (all interfaces)
PORT=8000     # Default: 8000

streamable-http サーバーの起動

# Basic streamable-http server startup
TRANSPORT=streamable-http uvx yandex-tracker-mcp@latest

# With custom host and port
TRANSPORT=streamable-http \
HOST=localhost \
PORT=9000 \
uvx yandex-tracker-mcp@latest

# With all environment variables
TRANSPORT=streamable-http \
HOST=0.0.0.0 \
PORT=8000 \
TRACKER_TOKEN=your_token \
TRACKER_CLOUD_ORG_ID=your_org_id \
uvx yandex-tracker-mcp@latest

MCP サーバーへの接続に以下の形式を使用する場合は、TRACKER_CLOUD_ORG_ID または TRACKER_ORG_ID の設定を省略できます（Claude Code の例）。

claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?cloudOrgId=your_cloud_org_id&"

または

claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?orgId=org_id&"

OAuth 2.0 認証を使用する場合は、グローバルな TRACKER_TOKEN 環境変数の設定も省略できます（下記を参照）。

OAuth 2.0 認証

Yandex Tracker MCP サーバーは、静的な API トークンに代わる安全な方法として、OAuth 2.0 認証に対応しています。設定すると、サーバーは OAuth プロバイダーとして動作し、MCP クライアントと Yandex OAuth サービス間の認証を仲介します。

OAuth の仕組み

MCP サーバーは、標準的な OAuth 2.0 認可コードフローを実装しています。

1. クライアント登録： MCP クライアントがサーバーに登録し、クライアント認証情報を取得します
2. 認可： ユーザーは認証のために Yandex OAuth にリダイレクトされます
3. トークン交換： サーバーが認可コードをアクセストークンと交換します
4. API アクセス： クライアントはすべての API リクエストでベアラートークンを使用します
5. トークンの更新： 期限切れのトークンは、再認証せずに更新できます

MCP Client → MCP Server → Yandex OAuth → User Authentication
    ↑                                           ↓
    └────────── Access Token ←─────────────────┘

OAuth の設定

OAuth 認証を有効にするには、以下の環境変数を設定します。

# Enable OAuth mode
OAUTH_ENABLED=true

# Yandex OAuth Application Credentials (required for OAuth)
OAUTH_CLIENT_ID=your_yandex_oauth_app_id
OAUTH_CLIENT_SECRET=your_yandex_oauth_app_secret

# Public URL of your MCP server (required for OAuth callbacks)
MCP_SERVER_PUBLIC_URL=https://your-mcp-server.example.com

# Optional OAuth settings
OAUTH_SERVER_URL=https://oauth.yandex.ru  # Default Yandex OAuth server

# When OAuth is enabled, TRACKER_TOKEN becomes optional

OAuth スコープ

OAUTH_USE_SCOPES=true（デフォルト）の場合、サーバーは Yandex Tracker のスコープ tracker:read と tracker:write を要求、通知、必須指定します。ただし、TRACKER_READ_ONLY=true の場合は tracker:read のみを使用するため、読み取り専用インスタンスで書き込みアクセスをユーザーに求めることはありません。OAUTH_USE_SCOPES=false に設定すると、フローからスコープが完全に除外されます。これは Yandex Cloud フェデレーションで必要な設定です。

Yandex OAuth アプリケーションの設定

1. Yandex OAuth にアクセスし、新しいアプリケーションを作成します
2. コールバック URL を次のように設定します：{MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback
3. 次の権限を要求します：
   • tracker:read - Tracker の読み取り権限
   • tracker:write - Tracker の書き込み権限
4. クライアント ID とクライアントシークレットを保存します

OAuth 認証と静的トークン認証の比較

OAuth モードの制限事項

• 現在、OAuth モードでは、コールバック URL を利用するために MCP サーバーがパブリックにアクセス可能である必要があります
• OAuth モードは、ウェブベースの認証フローに対応した対話型クライアントに最適です

MCP クライアントで OAuth を使用する

OAuth が有効な場合、MCP クライアントには次の対応が必要です：

1. OAuth 2.0 の認可コードフローに対応する
2. アクセストークンの有効期限が切れた際にトークンを更新する
3. 継続的な認証のためにリフレッシュトークンを安全に保管する

注：現在、OAuth 認証に対応していない MCP クライアントもあります。OAuth への対応状況については、クライアントのドキュメントを確認してください。

Claude Code の設定例：

claude mcp add --transport http yandex-tracker https://your-mcp-server.example.com/mcp/ -s user

OAuth データストレージ

MCP サーバーは、OAuth データ（クライアント登録、アクセストークン、リフレッシュトークン、認可状態）用に、2 種類のストレージバックエンドに対応しています：

InMemory ストア（デフォルト）

インメモリストアは、すべての OAuth データをサーバーのメモリに保持します。これがデフォルトのオプションで、追加の設定は不要です。

特性：

• 永続性：サーバーの再起動時にデータが失われます
• パフォーマンス：データがメモリに保存されるため、アクセスが非常に高速です
• スケーラビリティ：単一のサーバーインスタンスに限定されます
• セットアップ：追加の依存関係は不要です
• 最適な用途：再起動時に OAuth セッションが失われても問題のない、開発、テスト、または単一インスタンスのデプロイ

設定：

OAUTH_STORE=memory  # Default value, can be omitted

Redis ストア

Redis ストアは、Redis データベースを使用して OAuth データを永続的に保存します。これにより、OAuth セッションがサーバーの再起動後も維持され、複数インスタンスのデプロイが可能になります。

特性：

• 永続性：サーバーの再起動後もデータが保持されます
• パフォーマンス：ネットワークのオーバーヘッドはありますが、高速にアクセスできます
• スケーラビリティ：同じ Redis データベースを共有する複数のサーバーインスタンスに対応します
• セットアップ：Redis サーバーのインストールと設定が必要です
• 最適な用途：本番環境へのデプロイ、高可用性構成、または OAuth セッションの維持が必要な場合

設定：

# Enable Redis store for OAuth data
OAUTH_STORE=redis

# Redis connection settings (same as used for tools caching)
REDIS_ENDPOINT=localhost                  # Default: localhost
REDIS_PORT=6379                           # Default: 6379
REDIS_DB=0                                # Default: 0
REDIS_PASSWORD=your_redis_password        # Optional: Redis password
REDIS_POOL_MAX_SIZE=10                    # Default: 10

ストレージの動作：

• クライアント情報：永続的に保存されます
• OAuth 状態：セキュリティのため、TTL（有効期間）付きで保存されます
• 認可コード：TTL 付きで保存され、使用後に自動的に削除されます
• アクセストークン：トークンの有効期間に基づく自動有効期限付きで保存されます
• リフレッシュトークン：失効するまで永続的に保存されます
• キーの名前空間：他の Redis データとの競合を避けるため、oauth:* プレフィックスを使用します

トークンの暗号化（Redis ストアでは必須）

Redis ストアを使用する場合は、保存時の OAuth トークンを保護するために暗号化を設定する必要があります。トークンの値は Fernet（AES-128）を使って暗号化され、Redis のキーには生のトークンの代わりに SHA-256 ハッシュが使われます。これにより、Redis が侵害された場合でもトークンが漏えいするのを防げます。

暗号化キーを生成します：

python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

設定：

# Single encryption key
OAUTH_ENCRYPTION_KEYS=<base64-encoded-32-byte-key>

# Multiple keys for rotation (first encrypts, all decrypt)
OAUTH_ENCRYPTION_KEYS=<new-key>,<old-key>

キーのローテーションを行うと、キーをシームレスに更新できます。まず新しいキーを追加し、古いトークンの有効期限が切れるのを待ってから、古いキーを削除します。

重要な注意事項：

• どちらのストアも、ツールのキャッシュシステムと同じ Redis 接続設定を使用します
• Redis ストアを使用する場合は、Redis インスタンスが適切に保護され、アクセス可能であることを確認してください
• OAUTH_STORE 設定が影響するのは OAuth データの保存のみです。ツールのキャッシュには TOOLS_CACHE_ENABLED が使用されます
• Redis ストアは、言語間の互換性とデバッグ性を高めるために JSON シリアライゼーションを使用します

認証

Yandex Tracker MCP Server は、明確な優先順位に基づいた複数の認証方法をサポートしています。サーバーは、次の優先順位に従って、利用可能な最初の認証方法を使用します。

認証の優先順位

1. 動的 OAuth トークン（優先度が最も高い）

   • OAuth が有効で、ユーザーが OAuth フローで認証した場合
   • トークンはユーザーセッションごとに動的に取得および更新されます
   • 標準の Yandex OAuth と Yandex Cloud フェデレーション OAuth の両方をサポートします
   • 必須の環境変数：OAUTH_ENABLED=true、OAUTH_CLIENT_ID、OAUTH_CLIENT_SECRET、MCP_SERVER_PUBLIC_URL
   • フェデレーション OAuth 用の追加の環境変数：OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth、OAUTH_TOKEN_TYPE=Bearer、OAUTH_USE_SCOPES=false

2. パススルー Bearer OAuth トークン

   • MCP OAuth ミドルウェアからトークンが提供されない場合、サーバーは受信した Authorization: Bearer <token> ヘッダーから Yandex OAuth トークンを読み取ることができます
   • ユーザーを認証し、保存済みの Yandex OAuth トークンを特定して、リクエストごとに挿入する信頼できるリバースプロキシまたはゲートウェイの背後で役立ちます
   • OAuth モードが有効でアクティブな場合は、MCP OAuth のトークンが引き続き優先されます

3. 静的 OAuth トークン

   • 環境変数で指定する従来の OAuth トークン
   • すべてのリクエストで同じトークンを使用します
   • 必須の環境変数：TRACKER_TOKEN（OAuth トークン）

4. 静的 IAM トークン

   • サービス間認証用の IAM（Identity and Access Management）トークン
   • 自動化システムや CI/CD パイプラインに適しています
   • 必須の環境変数：TRACKER_IAM_TOKEN（IAM トークン）

5. 動的 IAM トークン（優先度が最も低い）

   • サービスアカウントの認証情報を使って自動的に取得されます
   • トークンは自動的に取得および更新されます
   • 必須の環境変数：TRACKER_SA_KEY_ID、TRACKER_SA_SERVICE_ACCOUNT_ID、TRACKER_SA_PRIVATE_KEY

認証シナリオ

シナリオ 1：動的トークンを使った OAuth（対話型の使用に推奨）

# Enable OAuth mode
OAUTH_ENABLED=true
OAUTH_CLIENT_ID=your_oauth_app_id
OAUTH_CLIENT_SECRET=your_oauth_app_secret
MCP_SERVER_PUBLIC_URL=https://your-server.com

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

シナリオ 2：静的 OAuth トークン（簡単な設定）

# OAuth token
TRACKER_TOKEN=your_oauth_token

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

シナリオ 3：リバースプロキシ背後でのパススルー Bearer トークン

信頼できるゲートウェイでユーザー認証とユーザーの Yandex OAuth トークンの検索を行い、そのトークンをリクエストヘッダーに含めて MCP サーバーへリクエストを転送する場合は、このモードを使用します。

Authorization: Bearer <user_yandex_oauth_token>

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

このパススルートークンは、MCP OAuth ミドルウェアからリクエスト用のアクセストークンが提供されていない場合にのみ使用されます。OAuth が有効なデプロイで MCP OAuth セッションがアクティブな場合は、MCP OAuth トークンが優先されます。

シナリオ 4：静的 IAM トークン

# IAM token
TRACKER_IAM_TOKEN=your_iam_token

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

シナリオ 5：サービスアカウントを使った動的 IAM トークン

# Service account credentials
TRACKER_SA_KEY_ID=your_key_id
TRACKER_SA_SERVICE_ACCOUNT_ID=your_service_account_id
TRACKER_SA_PRIVATE_KEY=your_private_key

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

シナリオ 6：OIDC アプリケーション向けのフェデレーション OAuth（上級）

# Enable OAuth with Yandex Cloud federation
OAUTH_ENABLED=true
OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth
OAUTH_TOKEN_TYPE=Bearer
OAUTH_USE_SCOPES=false
OAUTH_CLIENT_ID=your_oidc_client_id
OAUTH_CLIENT_SECRET=your_oidc_client_secret
MCP_SERVER_PUBLIC_URL=https://your-server.com

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

この設定では、Yandex Cloud OIDC アプリケーションを通じた認証を有効にします。これは、Yandex Cloud のフェデレーションアカウントに必要です。フェデレーションユーザーは、所属組織の ID プロバイダー（IdP）を通じて認証し、この OAuth フローを使用して Yandex Tracker API にアクセスします。

重要な注意事項

• サーバーは、上記の順序で認証方法を確認します
• 一度に使用される認証方法は 1 つだけです
• 本番環境での使用には、セキュリティを高めるため、動的トークン（OAuth または IAM）を推奨します
• IAM トークンは OAuth トークンより有効期間が短いため、より頻繁な更新が必要になる場合があります
• サービスアカウントを使用する場合は、そのアカウントに Yandex Tracker の適切な権限があることを確認してください

設定

環境変数

# Authentication (use one of the following methods)
# Method 1: OAuth Token
TRACKER_TOKEN=your_yandex_tracker_oauth_token

# Method 2: IAM Token
TRACKER_IAM_TOKEN=your_iam_token

# Method 3: Service Account (for dynamic IAM token)
TRACKER_SA_KEY_ID=your_key_id                    # Service account key ID
TRACKER_SA_SERVICE_ACCOUNT_ID=your_sa_id        # Service account ID
TRACKER_SA_PRIVATE_KEY=your_private_key          # Service account private key

# Organization Configuration (set exactly one - setting both is an error)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id    # For Yandex Cloud organizations
TRACKER_ORG_ID=your_org_id                # For Yandex 360 organizations

# API Configuration (optional)
TRACKER_API_BASE_URL=https://api.tracker.yandex.net  # Default: https://api.tracker.yandex.net
TRACKER_API_TIMEOUT=10                    # Default: 10 - Per-request timeout in seconds for Tracker API calls

# Security - Restrict access to specific queues (optional)
TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV      # Comma-separated queue keys - allow-list of accessible queues
TRACKER_READ_ONLY_QUEUES=PROJ2            # Comma-separated queue keys - allowed for reads but reject writes (per-queue read-only)
TRACKER_ENTITIES_ENABLED=true             # Default: false - Register project/portfolio/goal tools (NOT covered by the queue restrictions above)

# Server Configuration
HOST=0.0.0.0                              # Default: 0.0.0.0
PORT=8000                                 # Default: 8000
TRANSPORT=stdio                           # Options: stdio, streamable-http, sse

# Redis connection settings (used for caching and OAuth store)
REDIS_ENDPOINT=localhost                  # Default: localhost
REDIS_PORT=6379                           # Default: 6379
REDIS_DB=0                                # Default: 0
REDIS_PASSWORD=your_redis_password        # Optional: Redis password
REDIS_POOL_MAX_SIZE=10                    # Default: 10

# Tools caching configuration (optional)
TOOLS_CACHE_ENABLED=true                  # Default: false
TOOLS_CACHE_REDIS_TTL=3600                # Default: 3600 seconds (1 hour)

# OAuth 2.0 Authentication (optional)
OAUTH_ENABLED=true                        # Default: false
OAUTH_STORE=redis                         # Options: memory, redis (default: memory)
OAUTH_SERVER_URL=https://oauth.yandex.ru  # Default: https://oauth.yandex.ru (use https://auth.yandex.cloud/oauth for federation)
OAUTH_TOKEN_TYPE=<Bearer|OAuth|<empty>>   # Default: <empty> (required to be Bearer for Yandex Cloud federation)
OAUTH_USE_SCOPES=true                     # Default: true (set to false for Yandex Cloud federation)
OAUTH_CLIENT_ID=your_oauth_client_id      # Required when OAuth enabled
OAUTH_CLIENT_SECRET=your_oauth_secret     # Required when OAuth enabled
MCP_SERVER_PUBLIC_URL=https://your.server.com  # Required when OAuth enabled
TRACKER_READ_ONLY=true                    # Default: false - Disable all write tools for the whole instance

キューのアクセス制御

キューへのアクセスは、大まかな制御から細かな制御まで、次の 3 つのレベルで設定できます。

• TRACKER_LIMIT_QUEUES — キューキーの許可リストです。リストに含まれないキューは、読み取りと書き込みの両方で 見つからない／許可されていない として扱われます。ここでは TRACKER_READ_ONLY_QUEUES と同様に、大文字と小文字を区別せずにキーを照合するため、dev と DEV は同じキューを指します。唯一の例外はボードツールです。ボードはキューではなく組織に属するため、フィルタリングされず、ボードの設定で制限対象のキューを指定できます。
• TRACKER_READ_ONLY — true の場合、すべての書き込みツールが登録解除され、インスタンス全体が読み取り専用になります。
• TRACKER_READ_ONLY_QUEUES — キューごとの読み取り専用許可リストです。書き込みツールは登録されたままですが、リストに含まれるキューを対象とする変更操作（作成／更新／移動／コメント／作業ログ／リンク、キューバージョンの作成）は拒否されます。読み取りは引き続き可能です。リストに含まれないキューは読み書き可能なままです。

プロジェクト／ポートフォリオ／目標のツールは、このモデルの対象外です。 プロジェクト、ポートフォリオ、目標は単一のキューに確実に対応付けられないため、上記の 3 つの設定はいずれも適用されません。読み取りツール（project_get、project_find、*_get_comments、…）にも、書き込みツール（コメントやチェックリストのツールを含む）にも適用されません。これらを有効にすると、サーバーにアクセスできるユーザーに、それらのエンティティへの組織全体のアクセス権が付与されます。このため、これらはオプトイン方式です。TRACKER_ENTITIES_ENABLED=true（デフォルトは false）の場合にのみ登録されます。これにより、不要なデプロイ環境ではツールマニフェストを小さく保てます。TRACKER_READ_ONLY は引き続き適用され、ほかのすべての書き込みツールとともに、エンティティの書き込みツールも登録解除されます。

これにより、1 つのインスタンスで一部のキューは読み書き可能、ほかのキューは読み取り専用にできます。たとえば、TRACKER_LIMIT_QUEUES=DEV,MGMT と TRACKER_READ_ONLY_QUEUES=MGMT を組み合わせると、DEV には完全にアクセスでき、MGMT は読み取り専用で参照できます。これは、エンドユーザーがサーバー経由でのみ Tracker にアクセスし、生のトークンを直接保持しない共有 MCP ゲートウェイで特に便利です。

これらのチェックはプロセス内のガードレールです。生の Tracker トークンを保持するクライアントについては、実際の制限をトークン自体にも設定する必要があります。

Docker のデプロイ

ビルド済みイメージを使用する（推奨）

イメージのデフォルトは TRANSPORT=stdio です。この場合、コンテナの標準入力／標準出力を介して通信し、ポートは開きません。以下の例のように、HTTP 経由でサーバーにアクセスする場合は TRANSPORT=streamable-http を設定してください。stdio クライアントでは、代わりに -i を指定し、-p を指定せずにコンテナを実行します（MCP クライアントの設定の例を参照してください）。

# Using environment file (it must set TRANSPORT=streamable-http)
docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest

# With inline environment variables
docker run -e TRACKER_TOKEN=your_token \
           -e TRACKER_CLOUD_ORG_ID=your_org_id \
           -e TRANSPORT=streamable-http \
           -p 8000:8000 \
           ghcr.io/aikts/yandex-tracker-mcp:latest

イメージをローカルでビルドする

docker build -t yandex-tracker-mcp .

Docker Compose

ビルド済みイメージを使用する：

services:
  mcp-tracker:
    image: ghcr.io/aikts/yandex-tracker-mcp:latest
    ports:
      - "8000:8000"
    environment:
      - TRACKER_TOKEN=${TRACKER_TOKEN}
      - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
      - TRANSPORT=streamable-http

ローカルでビルドする：

services:
  mcp-tracker:
    build: .
    ports:
      - "8000:8000"
    environment:
      - TRACKER_TOKEN=${TRACKER_TOKEN}
      - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
      - TRANSPORT=streamable-http

開発環境のセットアップ

# Clone and setup
git clone https://github.com/aikts/yandex-tracker-mcp
cd yandex-tracker-mcp

# Install development dependencies
uv sync --dev

# Formatting and static checking
task

ライセンス

このプロジェクトは、LICENSE ファイルに記載された条件に基づいてライセンスされています。

サポート

問題やご質問については、以下をご確認ください。

• Yandex Tracker API のドキュメントを確認してください
• https://github.com/aikts/yandex-tracker-mcp/issues から問題を報告してください