TeamCity CI/CD

readonly-mcp-teamcity

AI エージェントが JetBrains TeamCity サーバーのプロジェクト、ビルド構成、ビルド、ログ、テスト結果、問題、キュー、エージェント、VCS 変更を参照できる、読み取り専用の Model Context Protocol（MCP）サーバーです。29 個のツールはすべて読み取り専用です。

クイックスタート

uv がインストールされていれば、ほかにインストールするものはありません。

claude mcp add teamcity \
  -e TEAMCITY_BASE_URL=https://teamcity.example.com \
  -e TEAMCITY_TOKEN=your-token \
  -- uvx readonly-mcp-teamcity

uvx はパッケージをキャッシュされた隔離環境にダウンロードして実行します。 Python 3.11 以降が必要です。

設計上、読み取り専用です。 このサーバーが発行するのは GET リクエストのみです（HTTP クライアントにほかのメソッドが追加されるとテストは失敗します）。TeamCity で何かをトリガー、キャンセル、ピン留め、タグ付け、変更することはできません。また、すべてのツールに readOnlyHint が付与されています。さらに防御を強化するため、TeamCity 側でトークンを読み取り専用に設定してください。トークンを参照してください。このサーバーについてはこちらの投稿、読み取り専用 MCP サーバーを構築する理由もご覧ください。

トークン

Profile → Access Tokens でトークンを作成します。Permissions scope を Limit per project に設定し、ルートプロジェクト（またはエージェントに表示させるプロジェクト）を選んで、Read-only プリセットを選択します。このようにスコープを設定したトークンは、クライアントが誤動作しても何も変更できません。

Read-only プリセットでは、TeamCity が読み取り専用として指定する 14 個の VIEW_* 権限が選択されます。これには、エージェントの詳細やサーバー設定に関するグローバル権限も含まれます。トークンに付与される権限は所有者の権限を超えません。Project viewer ロールのみを持つユーザーのトークンでもエージェント関連ツールは動作し、get_server_health はメトリクスを利用不可として報告しつつ、ヘルス項目を返します。ビルドのピン留めができないこと（HTTP 403）を含め、TeamCity 2026.2.1 で確認済みです。

ツール

プロジェクト

ツール	説明
search_projects	名前、ID、親プロジェクトでプロジェクトを検索し、階層を参照します。
get_project_details	子プロジェクト、ビルド構成、パラメーターを含むプロジェクトの全情報です。

ビルド構成

ツール	説明
search_build_configs	プロジェクト ID、ビルドタイプ ID、一時停止状態で構造化検索します。
find_build_config	構成名とプロジェクトパスをあいまい検索し、曖昧な一致を示して該当するプロジェクトを一覧表示します。
get_build_config_details	ステップ、トリガー、パラメーター、VCS ルート、設定、エージェント要件を取得します。
get_build_config_branches	構成がビルドできるブランチと、デフォルト／アクティブ状態を取得します。

ビルド

ツール	説明
search_builds	構成、プロジェクト、ステータス、ブランチ、日付などで絞り込んでビルド履歴を検索します。
get_build_details	1 件のビルドのステータス、エージェント、リビジョン、パラメーター、依存関係、テスト概要、タグを取得します。
get_build_statistics	所要時間、テスト数、カバレッジ、成果物サイズなどの数値メトリクスを取得します。
get_build_chain	スナップショット依存関係のチェーンを上流（依存先）と下流（依存元）にたどります。

ログ

ツール	説明
get_build_log	tail と行範囲指定に対応した、ページ単位のログ取得です。
search_build_log	ビルドログを全文検索し、前後のコンテキストを取得します。

テストと問題

ツール	説明
diagnose_build	ビルド失敗の原因を1回の呼び出しで確認します。問題、失敗したテスト（ミュートされていないものを先に表示）、ログのエラー行を取得します。
get_build_test_results	ビルドのテスト実行を、ステータスで絞り込んで取得します。
get_test_details	1件のテスト実行について、失敗理由、履歴の範囲、ミュート／調査の状態を取得します。
get_build_problems	構造化された失敗理由（コンパイル、終了コード、依存関係）を取得します。
search_investigations	プロジェクト、ビルド構成、担当者でアクティブな調査を検索します。
list_muted_tests	現在ミュートされているテストと、その適用範囲、ミュートした人、理由を表示します。

インフラストラクチャ

ツール	説明
get_build_queue	エージェントを待機中のビルドと、待機理由を取得します。
search_agents	接続／認証／有効化の状態と現在のビルドを含むビルドエージェントを検索します。
list_agent_pools	エージェント数とプロジェクト数を含むエージェントプールを一覧表示します。
get_agent_details	1台のエージェントの状態、有効化／認証に関するコメント、最終アクティビティ、現在のビルドを取得します。
list_build_artifacts	ビルドのアーティファクトツリーを参照します（ディレクトリ1階層分）。
get_build_artifact_content	テキスト形式のアーティファクトを読み込みます（サイズ上限あり、行単位でページ分割）。
search_changes	ビルド、構成、プロジェクト、コミッター、または特定のコミット以降のVCS変更（コミット）を検索します。
get_change_details	変更1件の、変更されたファイルの完全な一覧を取得します。
resolve_teamcity_url	TeamCityのWeb URLを解析し、プロジェクト／ビルド構成／ビルド／変更のIDを取得します。
get_server_info	TeamCityのバージョン、ビルド番号、稼働時間を取得します。
get_server_health	サーバーのヘルス項目とランタイムメトリクス（CPU、メモリ、キュー）を取得します。

インストール

インストールせずに実行します（推奨）：

uvx readonly-mcp-teamcity

または、環境にインストールします：

uv tool install readonly-mcp-teamcity   # or: pip install readonly-mcp-teamcity

Docker

このイメージは、ポート8080でストリーム可能なHTTPトランスポートを提供します。このトランスポートには認証機能がないため、ホストのループバックアドレスでのみ公開してください：

docker run --rm \
  -e TEAMCITY_BASE_URL=https://teamcity.example.com \
  -e TEAMCITY_TOKEN=your-token \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/desty2k/readonly-mcp-teamcity:latest

設定

すべての設定は TEAMCITY_* 環境変数で行います。

変数	必須	デフォルト	説明
TEAMCITY_BASE_URL	はい	—	TeamCityサーバーのベースURL（例：https://teamcity.example.com）。
TEAMCITY_TOKEN	はい	—	REST APIのベアラートークン。トークンを参照してください。
TEAMCITY_TIMEOUT	いいえ	30	HTTPリクエストのタイムアウト（秒）。
TEAMCITY_MAX_RETRIES	いいえ	3	一時的なネットワークエラー／5xxエラーに対する再試行回数。
TEAMCITY_POOL_MAX_CONNECTIONS	いいえ	20	httpx接続プールのサイズ。
TEAMCITY_DEFAULT_LIMIT	いいえ	50	リストツールのデフォルトのページサイズ。
TEAMCITY_MAX_LIMIT	いいえ	500	最大ページサイズ。
TEAMCITY_INDEX_REFRESH_INTERVAL	いいえ	300	ファジーインデックスを更新する間隔（秒）。読み込みに失敗した場合は、より早く再試行します。
TEAMCITY_LOG_CACHE_MAX_BYTES	いいえ	67108864	ビルドログキャッシュのサイズ上限。実行中のビルドのログはキャッシュされません。
TEAMCITY_LOG_CACHE_TTL	いいえ	300	完了したビルドのログがキャッシュに保持される秒数。
TEAMCITY_TRANSPORT	いいえ	stdio	stdio、http、または sse。
TEAMCITY_HTTP_HOST	いいえ	127.0.0.1	http／sseのバインドアドレス。これらのトランスポートには認証機能がありません。ループバック以外のアドレスを指定すると警告が記録されます。
TEAMCITY_HTTP_PORT	いいえ	8080	http／sseトランスポートのポート。
TEAMCITY_LOG_FORMAT	いいえ	json	json（本番環境）または text（ローカル開発環境）。
TEAMCITY_LOG_LEVEL	いいえ	INFO	DEBUG、INFO、WARNING、または ERROR。

コピーして貼り付けられるテンプレートについては、.env.exampleを参照してください。

OpenTelemetry トレース

トレースはオプトイン方式で、無効の場合は何も行いません。基本インストールには OTel SDK は含まれていません。追加機能をインストールして有効にすると、上流の TeamCity 呼び出しごとにスパンをエクスポートします。

pip install 'readonly-mcp-teamcity[otel]'
export TEAMCITY_OTEL_ENABLED=true
export TEAMCITY_OTEL_ENDPOINT=http://localhost:4317   # optional; falls back to OTEL_EXPORTER_OTLP_ENDPOINT

変数	デフォルト	説明
TEAMCITY_OTEL_ENABLED	false	トレースのマスタースイッチです。
TEAMCITY_OTEL_SERVICE_NAME	readonly-mcp-teamcity	すべてのスパンの service.name です。
TEAMCITY_OTEL_ENDPOINT	未設定	OTLP コレクターのエンドポイントです。
TEAMCITY_OTEL_PROTOCOL	grpc	grpc または http/protobuf です。
TEAMCITY_OTEL_CONSOLE_EXPORT	false	スパンも stderr に出力します。

MCP クライアントの設定

Claude Desktop

claude_desktop_config.json（macOS では ~/Library/Application Support/Claude/、Windows では %APPDATA%\Claude\）に追加します。

{
  "mcpServers": {
    "teamcity": {
      "command": "uvx",
      "args": ["readonly-mcp-teamcity"],
      "env": {
        "TEAMCITY_BASE_URL": "https://teamcity.example.com",
        "TEAMCITY_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

クイックスタートを参照してください。

比較

2026 年 11 月時点の情報です。これを前提にする前に、各プロジェクトの情報をご確認ください。

	このサーバー	JetBrains MCP (2026.1+)	Daghis 2.12.12	itcaat 1.0.8	kate-horshchar 1.4.0
書き込み操作	設計上、一切ありません	デフォルトの安全モードでは個人用ビルドのみ。brave mode ではさらに実行できます	デフォルトでは実行とキャンセルが可能。エージェントが切り替えられる完全モードもあります	実行、キャンセル、ピン留め、タグ付けが可能。無効化するスイッチはありません	ありません。GET のみです
実行場所	お使いのマシン	TeamCity サーバー（/app/mcp）	お使いのマシン	お使いのマシン	お使いのマシン
曖昧な名前から設定を検索	名前とプロジェクトパスを対象にしたファジー検索	ドキュメントに記載なし	ロケーターのみ	ロケーターの部分一致	なし
TeamCity URL を貼り付け	新形式、短縮形式、従来形式の URL に対応	ドキュメントに記載なし	なし	なし	なし

出典：JetBrains AI エージェント連携、 JetBrains/teamcity-mcp、 Daghis/teamcity-mcp、 itcaat/teamcity-mcp、 kate-horshchar/teamcity-qa-mcp。 JetBrains プラグインの README とヘルプページでは、brave mode がデフォルトで 有効かどうかの記述が一致していません。サーバーの設定をご確認ください。

エージェントに TeamCity 上で操作させたい場合は、組み込みサーバーをお使いください。エージェントには閲覧だけさせたい場合は、こちらをお使いください。

質問の例

• 「auth サービスのデプロイパイプラインを探してください。」
• 「Proj_Build の直近 10 件のビルドと、失敗したものを表示してください。」
• 「ビルド 12345 が失敗した理由は何ですか？」（diagnose_build を 1 回呼び出します）
• 「そのビルドで失敗したテストと、エラーの内容を教えてください。」
• 「ビルドログで OutOfMemoryError を検索してください。」
• 「現在オフラインのエージェントはどれですか？」
• 「ビルドキューの内容と、待機している理由を教えてください。」
• 「Payments プロジェクトの失敗を調査しているのは誰ですか？」
• 「このビルドに含まれるコミットを教えてください。」
• 「https://teamcity.example.com/buildConfiguration/Proj_Build/12345 を解決してください。」

開発

git clone https://github.com/desty2k/readonly-mcp-teamcity
cd readonly-mcp-teamcity
uv sync --all-extras
uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

実サーバーに対するライブスモークテスト（認証情報は .env から読み込みます）：

uv run python tests/smoke_test.py

ライセンス

MIT — LICENSE を参照してください。