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 .
License
MIT — see LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mcp_face_transform-2026.8.18.0.tar.gz.
File metadata
- Download URL: mcp_face_transform-2026.8.18.0.tar.gz
- Upload date:
- Size: 21.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.0.1 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
15e718c2ab8775c69178b7b794e681c24017fcd1c6bd16a8c9db7cdb336fce49
|
|
| MD5 |
59ac9fd5383121ee2144e6618226e01e
|
|
| BLAKE2b-256 |
0fe9edbea96bf15db59265c27f28ac17794219fa9b48aa97ffa2da8a11639410
|
File details
Details for the file mcp_face_transform-2026.8.18.0-py3-none-any.whl.
File metadata
- Download URL: mcp_face_transform-2026.8.18.0-py3-none-any.whl
- Upload date:
- Size: 20.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.0.1 CPython/3.12.3
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cdae29a1554d7bb1a1b8a0d45d44e4934f78ccaaa8f884f50687c9f40752b7d1
|
|
| MD5 |
4336f94100fe8751350b0b63c4534c03
|
|
| BLAKE2b-256 |
b95e50c5c1fc310733500247fc066b1d47ecb530f0a42afd380c7e5165c16c70
|
