mcp-face-transform

MCP 顔変換サーバー

Model Context Protocol（MCP）サーバーです。AceDataCloud Face Transform API を公開し、顔のキーポイント検出、美顔加工、年齢・性別変換、顔の入れ替え、アニメ風加工、ライブネス検出を提供します。

ステータス： すべての Face API は現在 アルファ版 です。インターフェースは変更される可能性があります。

機能

• キーポイント検出 — 顔ごとに90以上のランドマークを検出。複数の顔に対応
• 美顔加工 — 肌のなめらかさ、ホワイトニング、小顔加工、目の拡大
• 年齢変換 — ポートレートの年齢を変換、または若返らせます
• 性別変換 — 顔から受ける性別の印象を変換します
• 顔の入れ替え — ソース画像の顔をターゲット画像に移します（オプションで非同期 Webhook に対応）
• アニメ風加工 — ポートレートをアニメ／漫画風に描画します
• ライブネス検出 — ライブ撮影と、印刷物／画面の写真を判別します

接続方法：ホスト型 OAuth、API トークン、またはローカル stdio

ホスト型エンドポイントは https://face.mcp.acedata.cloud/mcp です。MCP クライアント用に、いずれかの方法を選択してください。

方法	使用する状況	認証情報の設定
ホスト型 OAuth	クライアントがリモート MCP OAuth に対応している場合	URL のみを追加し、AceDataCloud にサインインしてアクセスを承認します。クライアント設定にトークンを貼り付ける必要はありません。
ホスト型 API トークン	クライアントで OAuth を完了できない場合、または明示的な連携用認証情報が必要な場合	Authorization: Bearer … ヘッダーで AceDataCloud API トークンを送信します。ローカルのシークレットストアまたは環境変数に保管してください。
ローカル stdio	クライアントがローカル MCP プロセスを実行する場合	mcp-face-transform をインストールし、ACEDATACLOUD_API_TOKEN をそのプロセスに渡します。この方法でも AceDataCloud API を呼び出します。

ホスト型サービスは、OAuth メタデータと Dynamic Client Registration（DCR）を公開しています。DCR はクライアントアプリケーションを登録するものであり、API キーではありません。 OAuth でサインインすると、クライアントは発行された Bearer トークンを送信します。このトークンは、アカウントの API 認証情報を再利用する場合も、新たに作成する場合もあります。ブラウザーでサインインするには、引き続き AceDataCloud アカウントが必要です。ホスト型サービスは従量課金の可能性があります。実際の操作を行う前に、現在のサービスドキュメントと表示される料金を確認してください。同じサーバーに OAuth ログインと固定の Authorization ヘッダーを両方設定しないでください。

ホスト型 OAuth の例

• Claude と Claude Desktop のチャット： Customize → Connectors → Add custom connector でリモートカスタムコネクターを追加し、https://face.mcp.acedata.cloud/mcp を入力して、サインインを選択します。Claude から OAuth クライアントの登録方法を尋ねられたら、Register automatically を選択します。同意手続きを完了してください。Claude Desktop のローカルの claude_desktop_config.json は別途設定が必要です。Claude コネクターガイド。
• Claude Code： claude mcp add --transport http --scope user face https://face.mcp.acedata.cloud/mcp を実行し、続けて claude mcp login face を実行します。/mcp を確認してください。Claude Code MCP ガイド。
• Cursor： https://face.mcp.acedata.cloud/mcp のみを指定してリモートサーバーを追加します。プロジェクトで使う場合は、以下のエントリを <project>/.cursor/mcp.json にマージします。個人用の場合は ~/.cursor/mcp.json を使用します。Cursor MCP ガイド。
• VS Code / Copilot： MCP: Add Server を実行し、HTTP を選択して https://face.mcp.acedata.cloud/mcp を入力し、ブラウザーでのサインインを完了します。新しいポータブルなワークスペース設定では <project>/.mcp.json を使用します。以下の VS Code 固有の形式では <project>/.vscode/mcp.json またはユーザープロファイルを使用します。MCP: List Servers を確認してください。VS Code MCP の設定。
• Codex： codex mcp add face --url https://face.mcp.acedata.cloud/mcp を実行し、続けて codex mcp login face を実行します。ユーザー設定は ~/.codex/config.toml にあります。Codex 公式 MCP ガイド。

Cursor プロジェクト設定（OAuth）：

{
  "mcpServers": {
    "face": {"url": "https://face.mcp.acedata.cloud/mcp"}
  }
}

VS Code 固有のワークスペース設定（OAuth）：

{
  "servers": {
    "face": {"type": "http", "url": "https://face.mcp.acedata.cloud/mcp"}
  }
}

ホスト型 API トークン

1. Ace Data Cloud → Applicationsを開きます。サインインするか、先にアカウントを登録してください。
2. General applicationを探します。作成されていない場合は、Initialize General Applicationを選択してください。汎用キーではアカウントで利用可能なサービスを使用できますが、専用アプリケーションのキーはそのサービスに制限されます。必要なサービス／モデルへのアクセス権と現在の料金を確認してください。
3. アプリケーションカードからAPI Keyをコピーするか、Keys / Manage Keys → Createを開いて、この連携用の別のキーを作成します。個別に失効またはローテーションできるよう、見分けやすい名前を付けてください。
4. キーの作成時に、Expiration Time、Set Usage Limitation、Allowed APIsを確認してください。必要な制限のみを有効にし、呼び出す操作を許可してから、Createをクリックし、キー一覧からトークンをコピーします。タスクの照会権限があっても、生成の送信権限が付与されるわけではありません。最初のリクエストに必要な残高がアプリケーションにあることを確認してください。試用枠がある場合、その内容は現在アカウントに表示されているものが適用されます。
5. 引用符、空白、Bearer を含めず、トークンの値だけをコピーしてください。API Key／API Tokenフィールドにはこの生の値を入力します。手動で設定する HTTP Authorizationヘッダーにのみ、Bearer のプレフィックスが必要です。platform-...で始まるアカウント管理用トークンを生成 API キーの代わりに使うことはできません。

キーは、クライアントの認証情報ストアか、以下に示す環境変数に保存してください。プロンプト、共有ワークフロー、スクリーンショット、Git のコミットには絶対に含めないでください。認証に失敗した場合は、別のキーを作成する前に、コピーした値全体、アプリケーション／サービスへのアクセス権、有効期限、使用制限、残高を確認してください。

固定の Bearer ヘッダーを使用すると OAuth を迂回します。ヘッダーが無効な場合は、ブラウザーでのサインインを試す前に削除してください。保存した認証情報は非公開にしてください。

Claude Code では、サーバーの追加時にシェルがトークンを展開します。保存されたユーザー MCP 設定は秘密情報として扱ってください。

export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
claude mcp add --transport http --scope user face https://face.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer $ACEDATACLOUD_API_TOKEN"

Claude Code のプロジェクト設定では、<project>/.mcp.jsonに変数参照を記述し、Claude Code の起動環境でその変数を設定してください。

{
  "mcpServers": {
    "face": {
      "type": "http",
      "url": "https://face.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

Cursor では、~/.cursor/mcp.jsonまたはコミット対象外のプロジェクト設定で、異なる環境変数構文を使用します。

{
  "mcpServers": {
    "face": {
      "url": "https://face.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${env:ACEDATACLOUD_API_TOKEN}"}
    }
  }
}

VS Code では、MCP: Open User Configurationを実行し、このサーバーとマスクされた入力をマージしてください。${input:...}は VS Code のユーザー／ワークスペース形式用であり、Agent Host の.mcp.json形式には移植できません。

{
  "inputs": [
    {"id": "acedata-face-token", "type": "promptString", "description": "AceDataCloud API token", "password": true}
  ],
  "servers": {
    "face": {
      "type": "http",
      "url": "https://face.mcp.acedata.cloud/mcp",
      "headers": {"Authorization": "Bearer ${input:acedata-face-token}"}
    }
  }
}

Clineでは、MCP 設定 UI または CLI ファイル~/.cline/data/settings/cline_mcp_settings.jsonを使用します。リモートトランスポートの値はstreamableHttpです。JetBrains AI Assistantでは、**Settings → Tools → AI Assistant → Model Context Protocol (MCP)**からリモート URL を追加します。Zedでは、OAuth の場合は URL のみを指定したcontext_serversエントリーを使うか、ローカルの Bearer ヘッダーを追加します。これらのクライアントでは設定スキーマが異なるため、別のクライアントの JSON をコピーせず、各クライアントの最新 UI に従ってください。Cline · JetBrains · Zed。

ローカル stdio

パッケージをインストールし、ローカルプロセスに API トークンを設定します。

python -m pip install mcp-face-transform
export ACEDATACLOUD_API_TOKEN='YOUR_API_TOKEN'
mcp-face-transform

Claude Desktop のローカル MCP では、開発者向け設定から開くファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）にこのエントリーをマージします。uvx の使用には、PATH 上に uv が必要です。

{
  "mcpServers": {
    "face": {
      "command": "uvx",
      "args": ["mcp-face-transform"],
      "env": {"ACEDATACLOUD_API_TOKEN": "YOUR_API_TOKEN"}
    }
  }
}

このユーザーレベルのファイルは非公開にしてください。セルフホスト可能な HTTP では mcp-face-transform --transport http --port 8000 を使用します。適切なネットワーク制御と TLS 制御を行ったうえでのみ公開してください。ローカルで実行しても、AceDataCloud API が呼び出されます。

サービスを使用する前の確認

1. https://face.mcp.acedata.cloud/health が {"status":"ok"} を返すことは、エンドポイントへの接続可能性のみを確認します。
2. MCP クライアントがツールを読み込むことを確認します。face_get_usage_guide は参照用のツールであり、下流 API へのアクセスや残高は検証しません。
3. 現在のサービスドキュメントを確認した後、ドキュメントに記載されたサービス操作を使って、エンドツーエンドの確認を行います。

401 が発生した場合は、クライアントが使用した認証経路と、トークンまたは OAuth セッションが有効かどうかを確認してください。403 は、アカウントの権限またはコンテンツモデレーションによる失敗を示す場合があります。返されたエラーを確認してください。残高不足や下流サービスの失敗については、それぞれ個別に原因を調べる必要があります。ツールが一覧に表示されたり、タスクが送信されたりしても、結果が正常に得られたことの証明にはなりません。

ツールリファレンス

ツール	説明
face_detect_keypoints	顔ごとに 90 個以上のキーポイントを検出します（複数の顔に対応）。
face_beautify	スムージング、美白、小顔化、目の拡大を行います。
face_change_age	ポートレートの年齢を上げたり下げたりします。
face_change_gender	顔の性別の印象を変えます。
face_swap	ソースの顔をターゲット画像に移します（オプションで非同期 Webhook に対応）。
face_cartoonize	ポートレートを漫画風／アニメ風に描画します。
face_detect_liveness	ライブ撮影と、印刷写真／画面写真を区別します。
face_get_usage_guide	クライアント側のツール使用方法を簡潔にまとめたリファレンスです。

例

"Detect all faces in https://example.com/group.jpg and return their keypoints."
→ face_detect_keypoints(image_url="https://example.com/group.jpg")

"Lighten and smooth my portrait."
→ face_beautify(image_url="https://example.com/me.jpg", smoothing=15, whitening=25)

"Replace the face in the scene with the headshot."
→ face_swap(
    source_image_url="https://example.com/headshot.jpg",
    target_image_url="https://example.com/scene.jpg",
  )

Claude Desktop / Claude Code での設定

{
  "mcpServers": {
    "face-transform": {
      "command": "uvx",
      "args": ["mcp-face-transform"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

または、ベアラー認証を使ってホストされたエンドポイントを利用します。

{
  "mcpServers": {
    "face-transform": {
      "url": "https://face.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer your_api_token_here"
      }
    }
  }
}

開発

pip install -e ".[dev,test]"
pytest --cov=core --cov=tools
ruff check .

サービスの詳細

サービスの詳細

ライセンス

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