Appcircle MCP Server

公式

Appcircleの公式MCPサーバー

GitHub

Appcircle MCPで何ができますか？

ビルドプロファイルの一覧表示と検索 — get_build_profiles を使用して、ページネーションされたビルドプロファイルを取得し、名前でフィルタリングします。
ビルド設定とワークフローの確認 — get_build_profile_details、get_build_configuration_details、get_workflow_detail を使用して、特定のビルドプロファイル、その設定、ワークフローの詳細を取得します。
署名IDの確認 — get_certificates、get_keystores、get_provisioning_profiles、get_bundle_identifiers を介して、証明書、キーストア、プロビジョニングプロファイル、バンドル識別子を一覧表示します。
テストおよびエンタープライズ配布ステータスの確認 — get_distribution_profiles と get_distribution_profile_details で配布プロファイルとそのアプリバージョンを取得するか、get_store_profiles でエンタープライズストアプロファイルを確認します。
CI/CD ヘルスとビルド履歴レポートの生成 — 集計された傾向と根本原因分析には get_build_insights_report を、生のビルドレコードには get_build_history_report を使用します。

ドキュメント

Appcircle MCP Server

Appcircle 向け MCP サーバー: ビルド、署名 ID、テスト配布、エンタープライズアプリストア、ストアへの公開、レポートツールを、MCP 対応クライアント (Claude Desktop、Cursor、VS Code など) に提供します。Appcircle MCP Server は AI ツールと Appcircle の橋渡し役として機能し、AI エージェント、アシスタント、チャットボットが構造化され管理されたタスクレベルのツールを通じて Appcircle リソースに安全にアクセスし操作できるようにします。

ユースケース

CI/CD とワークフローインテリジェンス: パイプライン実行の監視、リリース状況の追跡、モバイル CI/CD ワークフローに関するインサイトの取得。
設定と環境のインサイト: ビルド設定や署名セットアップをクエリし、プロジェクトの設定状況や問題の発生源を把握。
レポートと運用インサイト: CI の安定性、繰り返し発生する問題、パイプラインのパフォーマンス、CI/CD 全体の健全性に関するサマリーを生成。

実行モード

MCP サーバーは 4 つの方法で使用できます。

モード	概要
1. リモートホスト	https://mcp.appcircle.io. に接続します。ローカルインストールは不要で、クライアントはリクエストごとに Appcircle トークン (例: `Authorization: Bearer <token>`) を送信します。
2. ローカル (stdio)	ソースからサーバーを実行します。リポジトリをクローンし、必要に応じて venv を使用し、`appcircle-mcp` を実行します (デフォルトのトランスポートは stdio)。Python と pip が必要です。環境変数 `APPCIRCLE_ACCESS_TOKEN` を設定してください。MCP クライアントはサーバーをサブプロセスとして実行します。
3. ローカル (streamable-http)	HTTP 経由でサーバーをローカル実行します。`--transport streamable-http` を使用し、必要に応じて `--host` / `--port` (例: `appcircle-mcp --transport streamable-http --host 127.0.0.1 --port 8000`) を指定します。クライアントはその URL に接続し、リクエストでトークンを送信します。
4. ローカル (Docker)	公式 Docker イメージをマシン上で実行します。Docker が必要です。イメージのデフォルトポートを使用するか、`--port` で上書きします。正確な使用方法はイメージのドキュメントを参照してください。

クライアント (Cursor、Claude など) の詳細な設定は、専用のインストールガイドに記載されています。このセクションは概要レベルの要約です。

インストール

クライアント固有のセットアップガイド:

Claude Applications - Claude Desktop および Claude Code CLI のインストールガイド。
Cursor IDE - Cursor IDE のインストールガイド。
Codex - Codex アプリおよび Codex CLI のインストールガイド。
Antigravity IDE - Antigravity IDE のインストールガイド。
VS Code (GitHub Copilot) - GitHub Copilot を使用した VS Code のインストールガイド。
Windsurf IDE - Windsurf IDE のインストールガイド。
Gemini CLI - Gemini CLI のインストールガイド。
GitHub Copilot CLI - GitHub Copilot CLI のインストールガイド。

設定 (環境変数)

変数	必須	説明
`APPCIRCLE_ACCESS_TOKEN`	はい (stdio のみ)	Appcircle API アクセストークン。stdio トランスポート使用時に必須です。streamable-http の場合、各クライアントが独自のトークンを送信します。トークンの取得方法についてはトークンの取得を参照してください。
`APPCIRCLE_API_URL`	いいえ	API ベース URL (デフォルト: `https://api.appcircle.io`。セルフホストユーザーは異なる場合があります)。
`APPCIRCLE_MCP_ALLOWED_HOST`	いいえ (streamable-http のみ)	MCP サーバーの公開ホスト名 (例: `mcp.appcircle.io`)。リバースプロキシの背後にデプロイする場合に設定し、サーバーがクライアントからの `Host` ヘッダーを受け入れるようにします。localhost の場合は省略します。
`APPCIRCLE_MCP_PORT`	いいえ (streamable-http のみ)	HTTP サーバーのバインドポート (デフォルト: `8000`)。指定された場合、`--port` によって上書きされます。特定のポートが必要なオンプレミスまたは Docker で役立ちます。
`LOG_LEVEL`	いいえ	ログレベル (例: `DEBUG`、`INFO`)。デフォルト: `INFO`。
`APPCIRCLE_EXCLUDED_TOOLSETS`	いいえ	除外するツールセットのカンマ区切りリスト (例: `build_module,report`)。下記のツールセットを参照してください。

これらをシェルまたは MCP クライアントの設定で設定してください。

ツールセット

利用可能なツールセット

以下のツールセットが利用可能です。

ツールセット	説明
`build_module`	ビルドプロファイル、設定、ワークフロー、コミット、パイプライン操作
`signing_identities`	署名 ID とバンドル識別子
`testing_distribution`	テスト配布プロファイルと配布詳細
`publish_to_stores`	公開プロファイルとストア公開操作
`enterprise_app_store`	エンタープライズアプリストアプロファイルとストア詳細
`report`	レポート: ビルド履歴、配布、署名、公開ステータス、関連レポート

1 つ以上のツールセットを除外して、そのツールが登録されないようにできます。除外は CLI 引数または APPCIRCLE_EXCLUDED_TOOLSETS 環境変数で設定でき、両方がマージ (和集合) されます。

CLI: --exclude toolset1 toolset2 または --exclude-toolsets toolset1,toolset2
環境変数: APPCIRCLE_EXCLUDED_TOOLSETS=build_module,report

除外を含む MCP 設定の例 (Cursor / Claude Desktop):

{
  "mcpServers": {
    "appcircle": {
      "command": "appcircle-mcp",
      "args": ["--exclude", "report"]
    }
  }
}

ツール

ツールは MCP tools/list を通じて公開されます。以下のリファレンスはツールセットごとにすべてのツールをリストしています。レスポンスの形式と例については docs/tool_contract.md を参照してください。

ビルド

get_build_profiles - 現在の組織のビルドプロファイルを取得します (ページネーション対応)。プロファイル名でフィルタリング可能。
- アクセスレベル: read
- page: ページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: ページサイズ (1-100)。デフォルト: 25。100 を超える値は 100 に制限されます。(数値、オプション)
- search: プロファイル名でフィルタリングするためのオプションの検索語 (大文字小文字を区別しない部分一致)。(文字列、オプション)
get_build_profile_details - ID で単一のビルドプロファイルを取得し、オプションでビルド設定を含めます。
- アクセスレベル: read
- profile_id: ビルドプロファイル ID (例: UUID)。(文字列、必須)
- configurations: true の場合、プロファイルのビルド設定も取得します。デフォルト: false。(ブール値、オプション)
get_build_configuration_details - プロファイル ID と設定 ID で単一のビルド設定を取得します。
- アクセスレベル: read
- profile_id: ビルドプロファイル ID (例: UUID)。(文字列、必須)
- configuration_id: ビルド設定 ID (例: UUID)。(文字列、必須)
get_build_profile_workflows - プロファイル ID でビルドプロファイルのワークフローを取得します。
- アクセスレベル: read
- profile_id: ビルドプロファイル ID (例: UUID)。(文字列、必須)
get_workflow_detail - ビルドプロファイル ID とワークフロー ID で単一のワークフローを取得します。
- アクセスレベル: read
- profile_id: ビルドプロファイル ID (例: UUID)。(文字列、必須)
- workflow_id: ワークフロー ID (例: UUID)。(文字列、必須)
get_commits_by_branch - ビルドブランチのコミットを取得します (ページネーション対応)。
- アクセスレベル: read
- branch_id: ブランチ ID (例: UUID)。(文字列、必須)
- page: ページ番号 (1 ベース)。size と共に指定するとページネーションが有効になります。デフォルト: 1。(数値、オプション)
- size: ページサイズ。page と共に指定するとページネーションが有効になります。デフォルト: 25、最大 100。(数値、オプション)
get_commit_details - コミット ID (UUID) またはコミットハッシュ (git SHA) で単一のコミットを取得します。commit_id または commit_hash のいずれかを指定し、両方は指定しないでください。
- アクセスレベル: read
- commit_id: コミット ID (UUID)。(文字列、オプション)
- commit_hash: コミットハッシュ (git SHA)。(文字列、オプション)

署名 ID

get_bundle_identifiers - 組織のすべてのバンドル識別子 (iOS/macOS アプリバンドル ID) を取得します。
- アクセスレベル: read
- パラメータなし。
get_certificates - 組織のすべての署名証明書を取得します。機密フィールド (p12Password、p12Binary、metaData、thumbprint) は省略されます。
- アクセスレベル: read
- パラメータなし。
get_keystores - 組織のすべてのキーストア (例: Android 署名キーストア) を取得します。機密フィールド (password、aliasPassword、binary、checkSum、sha256FingerPrint) は省略されます。
- アクセスレベル: read
- パラメータなし。
get_provisioning_profiles - 組織のプロビジョニングプロファイル (例: iOS/macOS) を取得します。機密/大容量フィールド (binary、metaData、certificateThumbPrints、provisionedDevices、connectApiKeyId) は省略されます。オプションでアプリ (バンドル) ID でフィルタリング可能。
- アクセスレベル: read
- app_id: プロビジョニングプロファイルをフィルタリングするためのオプションのアプリ (バンドル) ID (例: com.example.app)。(文字列、オプション)

テスト配布

get_distribution_profiles - 現在の組織のテスト配布プロファイルを取得します (ページネーション対応)。プロファイル名でフィルタリング可能。
- アクセスレベル: read
- page: ページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: ページサイズ (1-100)。デフォルト: 25、最大 100。(数値、オプション)
- search: プロファイル名でフィルタリングするためのオプションの検索語。(文字列、オプション)
get_distribution_profile_details - ID で単一のテスト配布プロファイルを取得します (オプションのアプリバージョンページネーション付き)。
- アクセスレベル: read
- profile_id: 配布プロファイル ID (例: UUID)。(文字列、必須)
- page: アプリバージョンのページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: アプリバージョンのページサイズ (1-100)。デフォルト: 25、最大 100。(数値、オプション)

ストアへの公開

get_publish_profiles - 指定されたプラットフォームタイプの現在の組織の公開プロファイルを取得します (ページネーション対応)。フローステータスでフィルタリング可能。
- アクセスレベル: read
- platform_type: 公開プロファイルのプラットフォームタイプ ("ios" または "android")。(文字列、必須)
- page: ページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: ページサイズ (1-100)。デフォルト: 25、最大 100。(数値、オプション)
- flow_status: フィルタリングするためのオプションのフローステータスコード (例: 0=成功、1=失敗、91=実行中)。(数値、オプション)
get_publish_profile_details - プラットフォームタイプと ID で単一の公開プロファイルを取得します (オプションのアプリバージョンページネーション付き)。
- アクセスレベル: read
- platform_type: プラットフォームタイプ ("ios" または "android")。(文字列、必須)
- profile_id: 公開プロファイル ID (例: UUID)。(文字列、必須)
- page: アプリバージョンのページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: アプリバージョンのページサイズ (1-100)。デフォルト: 25、最大 100。(数値、オプション)

エンタープライズアプリストア

get_store_profiles - 現在の組織のエンタープライズアプリストアプロファイルを取得します (ページネーション対応)。
- アクセスレベル: read
- page: ページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: ページサイズ (1-100)。デフォルト: 25、最大 100。(数値、オプション)
get_store_profile_details - ID で単一のエンタープライズアプリストアプロファイルを取得します (オプションのアプリバージョンページネーション付き)。
- アクセスレベル: read
- profile_id: エンタープライズアプリストアプロファイル ID (例: UUID)。(文字列、必須)
- page: アプリバージョンのページ番号 (1 ベース)。デフォルト: 1。(数値、オプション)
- size: アプリバージョンのページサイズ (1-100)。デフォルト: 25、最大 100。(数値、オプション)

レポート

- **get_build_history_report** - ビルド履歴レポートを取得します。日付範囲、ビルドプロファイル、組織でフィルタリング可能。ページネーション対応。 - **アクセスレベル:** read - `start_date`: 開始日 (YYYY-MM-DD) (任意)。(string, optional) - `end_date`: 終了日 (YYYY-MM-DD) (任意)。(string, optional) - `page`: ページ番号 (デフォルト: 1)。(number, optional) - `size`: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional) - `build_profile_name`: ビルドプロファイル名でフィルタリング。(string, optional) - `organization_id`: 組織UUIDでフィルタリング。(string, optional)

get_build_insights_report - ビルド履歴に基づき、サーバーサイドで集計されたビルドインサイトレポート (ヘルススナップショットとトレンド、根本原因、アーティファクト健全性、ワークフロー品質、キュー時間、成熟度評価分析) を取得します。get_build_history_report とは異なり、内部的に全ページを取得し、生レコードではなく事前集計された小さな結果を返します。
- アクセスレベル: read
- start_date: 現在の期間の開始日 (YYYY-MM-DD) (任意)。デフォルト: 過去30日間。(string, optional)
- end_date: 現在の期間の終了日 (YYYY-MM-DD) (任意)。(string, optional)
- sections: 計算するセクションのリスト (任意): health_snapshot、root_cause、artifact_health、workflow_quality、queue_time、maturity_assessment。デフォルト: 全6項目。(array of strings, optional)
- include_sub_orgs: true の場合、履歴由来のメトリクスにおいて、トークン自身の組織にフィルタリングせず、組織横断的なビルドレコードを保持します。デフォルト: false。(boolean, optional)
get_distribution_app_version_report - 配布アプリバージョンの日次使用状況レポートを取得します。ページネーション対応。プロファイル、OS、組織でフィルタリング可能。
- アクセスレベル: read
- start_date: 開始日 (YYYY-MM-DD) (任意)。(string, optional)
- end_date: 終了日 (YYYY-MM-DD) (任意)。(string, optional)
- page: ページ番号 (デフォルト: 1)。(number, optional)
- size: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional)
- profile_name: 配布プロファイル名でフィルタリング。(string, optional)
- os: OSでフィルタリング ("ios" または "android")。(string, optional)
- organization_id: 組織UUIDでフィルタリング。(string, optional)
get_distribution_sent_report - 配布アプリ共有の日次使用状況レポートを取得します。ページネーション対応。プロファイル、OS、組織でフィルタリング可能。
- アクセスレベル: read
- start_date: 開始日 (YYYY-MM-DD) (任意)。(string, optional)
- end_date: 終了日 (YYYY-MM-DD) (任意)。(string, optional)
- page: ページ番号 (デフォルト: 1)。(number, optional)
- size: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional)
- profile_name: 配布プロファイル名でフィルタリング。(string, optional)
- os: OSでフィルタリング ("ios" または "android")。(string, optional)
- organization_id: 組織UUIDでフィルタリング。(string, optional)
get_enterprise_app_store_app_usage_report - エンタープライズアプリストアのアプリ使用状況レポートを取得します。start_date と end_date は必須。ページネーション対応。
- アクセスレベル: read
- start_date: 開始日 (YYYY-MM-DD)。(string, required)
- end_date: 終了日 (YYYY-MM-DD)。(string, required)
- page: ページ番号 (デフォルト: 1)。(number, optional)
- size: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional)
- organization_id: 組織UUIDでフィルタリング (任意)。(string, optional)
get_publish_resign_report - 公開再署名レポートを取得します。日付範囲、アプリ名、組織、ステータスでフィルタリング可能。ページネーション対応。
- アクセスレベル: read
- start_date: 開始日 (YYYY-MM-DD) (任意)。(string, optional)
- end_date: 終了日 (YYYY-MM-DD) (任意)。(string, optional)
- page: ページ番号 (デフォルト: 1)。(number, optional)
- size: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional)
- app_name: アプリ名でフィルタリング。(string, optional)
- organization_id: 組織UUIDでフィルタリング。(string, optional)
- status: 再署名ステータスでフィルタリング (0=待機中, 1=処理中, 2=成功, 3=失敗, 4=キャンセル, 5=タイムアウト)。(number, optional)
get_publish_status_report - 公開ステータスレポートを取得します。日付範囲、アプリ名、組織、ステータスでフィルタリング可能。ページネーション対応。
- アクセスレベル: read
- start_date: 開始日 (YYYY-MM-DD) (任意)。(string, optional)
- end_date: 終了日 (YYYY-MM-DD) (任意)。(string, optional)
- page: ページ番号 (デフォルト: 1)。(number, optional)
- size: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional)
- app_name: アプリ名でフィルタリング。(string, optional)
- organization_id: 組織UUIDでフィルタリング。(string, optional)
- status: 公開ステータスでフィルタリング (例: 0=成功, 1=失敗, 91=実行中)。(number, optional)
get_signing_report - 署名レポートを取得します。日付範囲、組織、OS、ビルドステータスでフィルタリング可能。ページネーション対応。
- アクセスレベル: read
- start_date: 開始日 (YYYY-MM-DD) (任意)。(string, optional)
- end_date: 終了日 (YYYY-MM-DD) (任意)。(string, optional)
- page: ページ番号 (デフォルト: 1)。(number, optional)
- size: 1ページあたりのアイテム数 (1-100、デフォルト: 50)。(number, optional)
- organization_id: 組織UUIDでフィルタリング。(string, optional)
- os: OSでフィルタリング ("ios" または "android")。(string, optional)
- build_status: ビルドステータスでフィルタリング (例: 0=成功, 1=失敗, 91=実行中)。(number, optional)

サーバーの実行

リポジトリルートから:

python -m src.server

または pip install -e . の後:

appcircle-mcp

サーバーは stdio (またはクライアントの起動方法に応じて SSE/HTTP) で実行されます。

レスポンス形式

すべてのツールは標準エンベロープを返します:

成功: { "success": true, "data": <payload>, "meta": { ... } }
data はツールの結果、meta はオプションです (例: count、page、filters)。
エラー: { "success": false, "error": { "tool", "type", "message", "details" } }
すべてのツールで同じ形式のため、クライアントは一貫してエラーを解析できます。

完全な仕様: docs/tool_contract.md

テスト

開発依存関係を含めてインストール:

pip install -e ".[dev]"

ユニットテスト (デフォルト)

モックAPIを使用します。APPCIRCLE_ACCESS_TOKEN は不要です。デフォルトの pytest はこれらのみを実行します (詳細は pyproject.toml の testpaths を参照):

pytest test/unit/ -v

単一ファイル: pytest test/unit/tools/build_module/test_get_build_profiles.py -v
カバレッジ付き: pytest test/unit/ --cov=src --cov-report=term-missing

統合テスト

実際の Appcircle API を呼び出します。環境変数に APPCIRCLE_ACCESS_TOKEN を設定し、以下を実行します:

pytest test/integration/ -v

すべての統合テスト: pytest test/integration/ -v
ツール別: pytest test/integration/build_module/ -v、pytest test/integration/report/ -v など
マーカー別: pytest -m integration -v (リポジトリルートから実行する場合。ユニットテストと統合テストの両方が収集される場合、統合テストのみを含みます)

APPCIRCLE_ACCESS_TOKEN が設定されていない場合、統合テストはスキップされます (失敗にはなりません)。

統合テスト用のオプション環境変数 (検出に失敗した場合やテストに実際のIDが必要な場合。省略するとそれらのテストはスキップされます):

変数	説明
`APPCIRCLE_TEST_ORGANIZATION_ID`	組織UUID。`test_with_organization_id` (エンタープライズアプリストアアプリ使用状況レポート) で使用されます。
`APPCIRCLE_TEST_BRANCH_ID`	ブランチUUID。APIからブランチを検出できない場合に、get_commits_by_branch および関連テストで使用されます。
`APPCIRCLE_TEST_COMMIT_ID`	コミットUUID。APIからコミットを検出できない場合に、get_commit_details テストで使用されます。

セキュリティ

このプロジェクトは pyproject.toml に記載されているサードパーティのオープンソースパッケージに依存しています。依存関係のバージョン範囲を固定し、暗号化ハッシュ付きのロックファイル (uv.lock) を提供していますが、これらのパッケージは独立してメンテナンスされており、「現状有姿」で提供されます。Appcircle は、サードパーティの依存関係のセキュリティや信頼性に関していかなる保証も行いません。

使用前にインストール済みパッケージを監査することを推奨します:

uv run pip-audit