MCP Face Transform Server

A Model Context Protocol (MCP) server that exposes the AceDataCloud Face Transform API — face keypoint detection, beautification, age/gender transform, face swap, cartoonization, and liveness detection.

Status: All Face APIs are currently in Alpha. Interfaces may evolve.

Features

Keypoint detection — 90+ landmarks per face, multi-face supported
Beautification — smoothing, whitening, face slimming, eye enlarging
Age transform — age or de-age a portrait
Gender transform — swap perceived facial gender characteristics
Face swap — move a source face onto a target image (with optional async webhook)
Cartoonize — render a portrait in animated / cartoon style
Liveness detection — distinguish live captures from printed / screen photos

Installation

pip install mcp-face-transform

Configuration

Set your AceDataCloud API token:

export ACEDATACLOUD_API_TOKEN=your_token_here

Get your token from https://platform.acedata.cloud.

Usage

stdio mode (default)

mcp-face-transform

HTTP mode

mcp-face-transform --transport http --port 8000

Tool Reference

Tool	Description
`face_detect_keypoints`	Detect 90+ keypoints per face (multi-face supported).
`face_beautify`	Smoothing, whitening, face slimming, and eye enlarging.
`face_change_age`	Age or de-age a portrait.
`face_change_gender`	Swap perceived facial gender characteristics.
`face_swap`	Move a source face onto a target image (with optional async webhook).
`face_cartoonize`	Render a portrait in cartoon / animated style.
`face_detect_liveness`	Distinguish a live capture from a printed / screen photo.
`face_get_usage_guide`	Concise client-side tool usage reference.

Example

"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",
  )

Configuration in Claude Desktop / Claude Code

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

Or use the hosted endpoint with bearer auth:

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

Development

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

Service details

License

MIT — see LICENSE.

Metadata

Release files for mcp-face-transform 2026.9.29.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-face-transform 2026.9.29.0
File	Size	Uploaded
mcp_face_transform-2026.9.29.0.tar.gz	21.2 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcp-face-transform 2026.9.29.0
File	Interpreter	ABI	Platform	Reset
mcp_face_transform-2026.9.29.0-py3-none-any.whl 21.0 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 42.3 kB

Release files / mcp_face_transform-2026.9.29.0.tar.gz

Download URL	mcp_face_transform-2026.9.29.0.tar.gz
Size	21.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`eeecaab3f4c3a9566ccd3a69facb142dd0d80066f66f5b06c31208cf3bfb2f0f`
BLAKE2b-256 checksum How to use checksums	`403973a7dac8147c76c831f01e4490fb966cbacbede480b51bf0e30adcd4cec5`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.12.3`

Release files / mcp_face_transform-2026.9.29.0-py3-none-any.whl

Download URL	mcp_face_transform-2026.9.29.0-py3-none-any.whl
Size	21.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0e3108ff21a2cc0f6275a37676a90eb8d39eb991f60b33d21836421016d565f7`
BLAKE2b-256 checksum How to use checksums	`3175d48158cc55efe59129bdaf6de6b2d15044f427ebb7dd1eae6b27b9812d0d`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.0.1 CPython/3.12.3`