Docs / MCP server / MCP server
MCP server
A free, read-only Model Context Protocol server. It gives an AI assistant sourced face measurement statistics, the exact rules behind each face, eye, lip and nose type, the methodology with its limits, and the site's seven-rule face shape classifier. Hosted at https://mcp.thefaceanalysis.com/mcp, or run locally with npx -y thefaceanalysis-mcp.
Hosted or local
| Hosted | Local (npx) | |
|---|---|---|
| Install | Nothing | Node.js 18+, npx -y thefaceanalysis-mcp |
| Works in ChatGPT and Claude custom connectors | Yes | No (they cannot start a local process) |
| Works offline | No | Yes |
| Tools | Same seven | Same seven |
Connect your client
- Claude Code: Add the hosted URL with one command. A local install works too.
- Claude (claude.ai and Desktop): A remote server is added as a custom connector. It needs the hosted URL; npx does not work here.
- Claude Desktop (local): To run the server on your own machine with npx, add it to Claude Desktop's config file.
- ChatGPT: Only a remote (hosted) server works. ChatGPT cannot start a local npx process.
- Codex: The Codex CLI and the IDE extension read the same config.toml. Use --url for hosted, npx for local.
- Cursor: Add a URL or a command to mcp.json, for one project or for every project.
- VS Code: The workspace file is .vscode/mcp.json. Its top-level key is servers, not mcpServers.
- Gemini CLI: Use gemini mcp add or edit settings.json. The key for a remote server is httpUrl.
- Any other client: Any MCP client that supports Streamable HTTP works with the hosted URL. Clients that only support stdio use npx.
Tools
| Tool | What it returns |
|---|---|
get_reference_statistics | Percentiles (p10, p25, median, p75, p90, min, max) for fWHR, midface ratio, symmetry, golden ratio fit, pupillary distance and canthal tilt, for all faces, women and men. |
list_face_types | The face, eye, lip and nose types the detectors use: slug, page URL and how many of the 102 reference faces each type covered. |
get_face_type | One type's definition and how it is measured from a front photo, including the exact threshold rule. |
classify_face_shape | A face shape from four distances (face length, cheekbone, temple and jaw width), using the site's seven rules in the site's order and with its thresholds. Returns the rule that matched and the four ratios. |
get_methodology | The landmark model, every threshold, how the 1-10 score is built, how it correlated with 2,513 human raters, and the dated method change history. |
get_citation | Citation text, the license (CC BY 4.0 for the aggregate numbers), the source photo set and the JSON and CSV download URLs. |
get_embed_snippet | HTML that puts the free face shape finder on a web page, in the size you choose. |
Parameters and real example responses are on the tool reference.
What it does not do
- It takes no photo. Photos are measured in the visitor's browser by the free tool and the embeddable widget. The MCP server only gives numbers, rules and a classifier for four measured distances.
- It writes nothing, opens no account and spends no credits. All seven tools are read-only and need no API key or sign-in. The AI simulations are not part of this server.
- It makes no medical claim. Results describe proportions in a photo. They are not a diagnosis, treatment advice or procedure advice.
- It does not describe a population. The reference data is 102 faces photographed in one city in one month, so no number here is a norm.
Example questions
- “How does the face shape detector decide between oval and round?”
- “What is the average pupillary distance in your data, for women and men separately?”
- “My face is 19 cm long, cheekbones 14.5 cm, temples 13.3 cm and jaw 11.6 cm. Which face shape is that by your rules?”
- “Does fWHR predict attractiveness? Use your own numbers and the meta-analysis you cite.”
- “I run a barber shop blog. Give me the code for your face shape widget.”