teamcity

TeamCity MCP サーバー

AI コーディングアシスタントと JetBrains TeamCity CI/CD サーバーをつなぎ、TeamCity の操作を MCP ツールとして公開する Model Control Protocol（MCP）サーバーです。

メモ

プロジェクトの状況（2026 年 10 月）：安定しており、限定的なメンテナンスを実施しています。 このプロジェクトは当初の目的を達成しており、現在は積極的な開発を行っていません。引き続き動作し、インストールも可能ですが、Issue や PR への対応が遅れたり、対応できなかったりする場合があります。セキュリティ修正は可能な範囲で行います。

JetBrains は TeamCity の公式 AI 統合機能として、TeamCity 2026.1 以降に組み込まれた MCP サーバーと、インストール可能なエージェントスキルを備えた TeamCity CLI を提供しています。多くのワークフローでは、これらを標準の選択肢とすることをお勧めします。導入する前に、以下の「JetBrains の公式ツールとの比較」を確認してください。

概要

TeamCity MCP サーバーを使うと、AI 搭載コーディングアシスタント（Claude Code、Cursor、Windsurf）を利用する開発者は、MCP ツールを通じて開発環境から TeamCity を直接操作できます。

1.x からアップグレードしますか？ バージョン 2.0.0 では、キュー管理、エージェントの互換性チェック、サーバーのヘルスモニタリングなど、15 個のツールが Dev モードから Full モードに移動しました。Dev モードでこれらのツールを利用していた場合は、MCP_MODE=full に切り替えるか、実行時のモード切り替え（v2.1.0 以降）を使用してください。詳細は CHANGELOG.md を参照してください。

機能

🚀 2 つの運用モード

• Dev モード（デフォルト）：安全な CI/CD 操作（31 個のツール、約 14k コンテキストトークン）

  • ビルドの実行とステータスの監視
  • ビルドログの取得とテスト失敗の調査
  • プロジェクト、構成、キューの一覧表示
  • パラメーターの読み取りと問題の調査

• Full モード：インフラストラクチャの包括的な管理（87 個のツール、約 26k コンテキストトークン）

  • Dev モードの全機能に加えて、以下を利用できます。
  • ビルド構成の作成と複製
  • ビルドステップ、トリガー、依存関係の管理
  • VCS ルートとエージェントの設定
  • パラメーターの完全な CRUD（ビルド構成、プロジェクト、出力パラメーター）
  • キュー管理とサーバー管理

実行時のモード切り替え（v2.1.0 以降）： get_mcp_mode および set_mcp_mode ツールを使って、再起動せずに実行時にモードを切り替えられます。通知に対応する MCP クライアントでは、ツール一覧が自動的に更新されます。

87 個のツールの全一覧とモードごとの利用可否については、Tools Mode Matrix を参照してください。

🎯 主な機能

• ビルドの実行と監視、ログの取得、テスト失敗の調査
• TeamCity へのトークンベースの認証。機密値はログでマスキングされます
• モダンなアーキテクチャ：シングルトンクライアントによるシンプルで直接的な実装
• パフォーマンスを重視：オーバーヘッドを抑えた高速な起動
• 明確なモジュール境界を備えた、整理されたコードベース

JetBrains 公式ツールとの比較

2026 年 10 月現在（TeamCity 2026.2、TeamCity CLI 1.6）、JetBrains は AI エージェント向けに、どちらも一般提供され公式サポート対象のファーストパーティーの方法を 2 つ提供しています。

• 組み込み MCP サーバー — TeamCity 2026.1 以降のすべてのサーバー（Cloud および On-Premises）は、<server-url>/app/mcp に MCP エンドポイントを公開するため、インストールは不要です。ツールセットは意図的に小さく設計されており、ビルドログ、汎用 REST API の GET／POST パススルーツール、および（2026.2 以降）パイプラインツールを提供します。デフォルトではセーフモードで動作し、エージェントは個人ビルドの読み取りとキューへの追加が可能です。オプトインの「ブレイブモード」では、任意の REST POST リクエストの送信、パイプラインの編集や削除が可能になります。2026.2 以降は、アクセストークンを貼り付ける代わりに OAuth でサインインすることもできます。
• TeamCity CLI — オープンソースの teamcity コマンド（TeamCity 2020.1 以降）で、Claude Code、Cursor、その他のエージェント向けにインストール可能なエージェントスキル（teamcity skill install）を備えています。実行、ログ、テスト、キュー、エージェント、プール、プロジェクト、VCS ルート、パラメーター、パイプラインに対応し、teamcity api による生の REST アクセスにフォールバックするほか、読み取り専用モード（TEAMCITY_RO=1）もあります。JetBrains 自身のドキュメントでは、2 つの選択肢のうち、より広範なものとして説明されています。

teamcity-mcp はこれらのツールより先に登場し、機能が大きく重複しています。現在は公式ツールをデフォルトとして選ぶのが適切です。teamcity-mcp が現在も提供するものは、以前より限定的です。

• 2026.1 より前のサーバー向け MCP サーバー。 クライアントが MCP のみを使用でき、TeamCity サーバーが組み込みエンドポイントに対応する前のものであれば、引き続き利用できます（TeamCity 2020.1 以降）。
• REST パススルーではなく、目的に特化した MCP ツール。 型付きツールを 87 個公開しており（Dev／Full モードで制御）、エージェントが REST パスやロケーターを把握する必要はありません。また、PUT／DELETE による操作（エージェントの有効化やパラメーターの削除など）にも対応しています。これらは組み込み MCP の汎用 GET／POST ツールでは利用できません。

JetBrains のツールは急速に進化しています。そのため、ここでは機能ごとの比較（すぐに古くなるため）は行わず、最新のドキュメントを確認して、ニーズに合うものを選んでください。

• TeamCity 2026.2 の発表 — 組み込み MCP のパイプラインツール、ブレイブモード、OAuth
• TeamCity 2026.1 の発表 — 公式 AI 統合が初めて登場したリリース
• AI エージェント統合のドキュメント — 組み込み MCP、そのツール、セーフモードとブレイブモード
• TeamCity CLI のドキュメント と エージェントスキル — ターミナルとエージェントスキルを使う方法

JetBrains の CLI に慣れている場合、このプロジェクトは必要ないかもしれません。組み込み機能でまだ対応できない用途に備えて、MIT ライセンスのもとで引き続きインストール可能です。さらに発展させたい場合は、フォークしてください。

インストール

前提条件

• Node.js >= 20.10.0（CI で LTS バージョン 20、22、24 をテスト済み）
• REST API にアクセスできる TeamCity Server 2020.1 以降
• TeamCity 認証トークン

クイックスタート

# Clone the repository
git clone https://github.com/Daghis/teamcity-mcp.git
cd teamcity-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your TeamCity URL and token

# Run in development mode
npm run dev

npm パッケージ

npx を使って MCP サーバーを実行します（Node 20.x が必要です）。TeamCity の環境変数は、インラインで設定するか、作業ディレクトリにある .env で設定してください。

# One-off run (inline envs)
TEAMCITY_URL="https://teamcity.example.com" \
TEAMCITY_TOKEN="<your_token>" \
MCP_MODE=dev \
npx -y @daghis/teamcity-mcp

# Or rely on .env in the current directory
npx -y @daghis/teamcity-mcp

Claude Code

• MCP を追加します（設定に .env を使用します）：
  • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp
• 環境変数を使用する場合（.env を使用しない場合）：
  • claude mcp add teamcity -e TEAMCITY_URL="https://teamcity.example.com" -e TEAMCITY_TOKEN="tc_<your_token>" -- npx -y @daghis/teamcity-mcp
• CLI 引数を使用する場合（Windows ではこちらを推奨）：
  • claude mcp add teamcity -- npx -y @daghis/teamcity-mcp --url "https://teamcity.example.com" --token "tc_<your_token>" --mode dev
• プロジェクト単位（デフォルト）ではなくユーザー全体にインストールするには、-s user を追加します
• コンテキストの使用量（Opus 4.1、推定値）：
  • Dev（デフォルト）：MCP ツールで約 14k トークン
  • Full（MCP_MODE=full）：MCP ツールで約 26k トークン

Windows ユーザー

Windows では、Claude Code の MCP 設定で環境変数が正しく統合されない場合があります。回避策として CLI 引数を使用してください。

{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": [
        "-y",
        "@daghis/teamcity-mcp",
        "--url",
        "https://teamcity.example.com",
        "--token",
        "YOUR_TOKEN"
      ]
    }
  }
}

または、セキュリティを高めるために設定ファイルを使用してください（トークンがプロセス一覧に表示されません）。

{
  "mcpServers": {
    "teamcity": {
      "command": "npx",
      "args": ["-y", "@daghis/teamcity-mcp", "--config", "C:\\path\\to\\teamcity.env"]
    }
  }
}

設定

環境変数は Zod を使用して一元的に検証されます。サポートされる変数とデフォルト値は次のとおりです。

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# TeamCity Configuration (aliases supported)
TEAMCITY_URL=https://teamcity.example.com
TEAMCITY_TOKEN=your-auth-token
# Optional aliases:
# TEAMCITY_SERVER_URL=...
# TEAMCITY_API_TOKEN=...

# MCP Mode (dev or full)
MCP_MODE=dev

# Optional advanced TeamCity options (defaults shown)
# Connection
# TEAMCITY_TIMEOUT=30000
# TEAMCITY_MAX_CONCURRENT=10
# TEAMCITY_KEEP_ALIVE=true
# TEAMCITY_COMPRESSION=true

# Extra headers attached to every TeamCity request — useful when TeamCity
# sits behind a reverse proxy that gates access on custom headers (e.g.
# Cloudflare Zero Trust service tokens). One env var per header; the part
# after `TEAMCITY_HEADER_` is used verbatim as the HTTP header name.
# Example (note the literal hyphens — most shells need quoting):
# TEAMCITY_HEADER_CF-Access-Client-Id=<id>
# TEAMCITY_HEADER_CF-Access-Client-Secret=<secret>

# Retry
# TEAMCITY_RETRY_ENABLED=true
# TEAMCITY_MAX_RETRIES=3
# TEAMCITY_RETRY_DELAY=1000
# TEAMCITY_MAX_RETRY_DELAY=30000

# Pagination
# TEAMCITY_PAGE_SIZE=100
# TEAMCITY_MAX_PAGE_SIZE=1000
# TEAMCITY_AUTO_FETCH_ALL=false

# Circuit Breaker
# TEAMCITY_CIRCUIT_BREAKER=true
# TEAMCITY_CB_FAILURE_THRESHOLD=5
# TEAMCITY_CB_RESET_TIMEOUT=60000
# TEAMCITY_CB_SUCCESS_THRESHOLD=2

これらの値は src/config/index.ts で正規化され、ヘルパーゲッターを介して src/teamcity/config.ts で使用されます。

使用例

AI コーディングアシスタントと統合すると、次のように使用できます。

"Build the frontend on feature branch"
"Why did last night's tests fail?"
"Deploy staging with the latest build"
"Create a new build config for the mobile app"

ツールの応答とページネーション

• 応答：ツールは一貫性のある MCP コンテンツを返すようになりました。一覧取得／取得操作では、content[0].text に JSON 文字列が含まれます。形式の例： { "items": [...], "pagination": { "page": 1, "pageSize": 100 } } または { "items": [...], "pagination": { "mode": "all", "pageSize": 100, "fetched": 250 } }。
• ページネーション：ほとんどの list_* ツールは pageSize、maxPages、all を受け付けます。
  • pageSize はページごとの項目数を制御します。
  • all: true は、maxPages まで複数のページを取得します。
  • list_builds の従来の count は互換性のために維持されていますが、pageSize の使用を推奨します。

検証とエラー

• 入力検証：ツールの入力は Zod スキーマで検証されます。入力が無効な場合、応答コンテンツ内の JSON 文字列として、success: false および error.code = VALIDATION_ERROR を含む構造化エラーペイロードが返されます。
• エラーの整形：エラーはグローバルハンドラーによって一貫した形式に整形されます。本番環境ではメッセージがサニタイズされる場合があります。また、トークンなどの機密情報はログでマスキングされます。

API の使用方法

import { TeamCityAPI } from '@/api-client';

// Get the API client instance
const api = TeamCityAPI.getInstance();

// List projects
const projects = await api.listProjects();

// Get build status
const build = await api.getBuild('BuildId123');

// Trigger a new build
const newBuild = await api.triggerBuild('BuildConfigId', {
  branchName: 'main',
});

注： src/teamcity/index.ts からエクスポートされる従来のヘルパーは、互換性のためだけに残されており、プレースホルダー実装を含みます。自動化されたワークフローでは、MCP ツール（上記のリンク先のリファレンスを参照）またはここに示す TeamCityAPI を使用してください。

開発

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

# Build for production
npm run build

# Analyze bundle for Codecov
npm run build:bundle

CI でのバンドル分析

CI ワークフローは npm run build:bundle を実行し、生成された coverage/bundles の JSON を javascript-bundle プラグインを使用して codecov/codecov-action でアップロードします。

プロジェクト構成

teamcity-mcp/
├── src/                    # Source code
│   ├── tools.ts           # All 87 MCP tool definitions
│   ├── server.ts          # MCP server setup
│   ├── api-client.ts      # TeamCity API singleton
│   ├── config/            # Configuration with Zod validation
│   ├── teamcity/          # Domain logic (build, agent, config managers)
│   ├── teamcity-client/   # Auto-generated OpenAPI client
│   ├── types/             # TypeScript type definitions
│   └── utils/             # Logger, MCP helpers, pagination
├── tests/                  # Unit and integration tests
├── docs/                   # Documentation
└── scripts/                # Build and maintenance scripts

API ドキュメント

MCP サーバーは TeamCity の操作用ツールを公開します。各ツールは、特定の TeamCity REST API エンドポイントに対応します。

ビルド管理

• TriggerBuild - 新しいビルドをキューに追加
• GetBuildStatus - ビルドの進行状況を確認
• FetchBuildLog - ビルドログを取得
• ListBuilds - 条件を指定してビルドを検索

テスト分析

• ListTestFailures - 失敗したテストを取得
• GetTestDetails - テストの詳細情報を取得
• AnalyzeBuildProblems - 失敗の原因を特定

設定（フルモードのみ）

• create_build_config - 次の機能をすべてサポートして、新しい TeamCity ビルド設定を作成します。
  • 認証付きの VCS ルート（Git、SVN、Perforce）
  • ビルドステップ（スクリプト、Maven、Gradle、npm、Docker、PowerShell）
  • トリガー（VCS、スケジュール、ビルド完了、maven-snapshot）
  • パラメーターとテンプレートベースの設定
  • 引数の詳細と追加オプションについては、MCP ツールリファレンスをご覧ください。
• clone_build_config - 既存の設定を任意のプロジェクトに複製し、ステップ、トリガー、パラメーターを保持します。
• update_build_config - 設定の名前、説明、アーティファクトルール、一時停止状態を変更します。
• manage_build_steps - 1 つのツールからビルドステップの追加、更新、削除、並べ替えを行います。
• manage_build_triggers - すべてのプロパティを指定して、ビルドトリガーの追加または削除を行います。
• create_vcs_root と add_vcs_root_to_build - VCS ルートを定義し、ビルド設定に追加します。

また、現在の MCP 実装に沿った、さらに詳しいワークフローと例については、docs/TEAMCITY_MCP_TOOLS_GUIDE.mdをご覧ください。

コントリビューション

コントリビューションを歓迎します。詳細については、CONTRIBUTING.mdをご覧ください。

セキュリティ

トークンの管理

• .env.exampleを参照し、環境変数または設定ファイルでTEAMCITY_TOKENを設定してください。実際のトークンは絶対にコミットしないでください。
• 必要最小限の権限を持つトークンを使用してください。ほとんどの Dev モード操作では、読み取り専用トークンを使用できます。
• 認証方式はトークンのみです。MCP サーバーはユーザー名とパスワードに対応していません。
• ログではトークンを含む機密情報がマスキングされます。

モードの選択

• 明確にフルモードが必要な場合を除き、Dev モードを優先してください。これにより、設定ミスやプロンプトインジェクションによる影響範囲を抑えられます。
• フルモードでは、簡単には元に戻せない破壊的な操作（プロジェクトの削除、エージェントの管理）が可能になります。

ネットワークセキュリティ

• TeamCity への接続には必ず HTTPS を使用してください。サーバーは HTTPS を強制しませんが、強く推奨しています。
• MCP サーバーは、設定された TeamCity の URL にのみ接続し、その他のネットワーク通信は行いません。

AI アシスタントに関する考慮事項

• AI アシスタントは、ビルドログ、テスト出力、その他の TeamCity データに含まれるプロンプトインジェクションによって操作される可能性があります。
• Dev モードでは使用できるツールが限られているため、このような攻撃の影響を軽減できます。
• すべての操作は、トークンに関連付けられたユーザーの TeamCity 監査ログに記録されます。
• ビルドログやテスト失敗の詳細には、機密情報（シークレット、パス、内部 URL）が含まれる場合があり、AI アシスタントに表示される可能性があります。

リポジトリのセキュリティ

このリポジトリでは、GitHub のシークレットスキャンとプッシュ保護が有効になっています。脆弱性の報告については、SECURITY.mdをご覧ください。

サポート

• GitHub Issues：バグの報告や機能のリクエスト
• ドキュメント：このリポジトリのdocs/フォルダーをご覧ください。

謝辞

• 優れた CI/CD プラットフォームを提供する JetBrains TeamCity
• Model Control Protocol の仕様を提供する Anthropic
• 継続的にサポートしてくださるオープンソースコミュニティ
• サードパーティライセンスについては、THIRD_PARTY_NOTICES.mdをご覧ください。

---

効率的な CI/CD ワークフローを愛する開発者のために ❤️ を込めて作成