About HeyBeauty MCP Server
HeyBeauty MCP Server is a TypeScript-based MCP server that provides virtual try-on through the HeyBeauty API. It is intended for developers and users who want to run try-on tasks from MCP clients.
Key features
- 01Clothes exposed as cloth:// resources
- 02Tool for submitting try-on tasks
- 03Tool for querying try-on task information
- 04Structured prompt for try-on with an LLM
Use cases
- 01Generating virtual try-on images from user photos in an MCP client
- 02Checking the status and result of a try-on task by task ID
- 03Browsing clothing resources to use in a try-on workflow
MCP support
This project is an MCP server that exposes clothing resources, try-on task tools and the tryon_cloth prompt to MCP clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
2Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| user_img_url | string | Yes | User image url, should be a url of a picture |
| cloth_img_url | string | Yes | Cloth image url, should be a url of a picture, user input or get from the selected cloth resource |
| cloth_id | string | No | Cloth id, get from the selected cloth resource |
| cloth_description | string | No | Cloth description, user input or get from the selected cloth resource |
Details
From the project READMEHeyBeauty MCP Server
HeyBeauty Virtual TryOn
This is a TypeScript-based MCP server that implements virtual tryon using HeyBeauty API. It demonstrates core MCP concepts by providing:
- Resources representing clothes with URIs and metadata
- Tools for submit tryon task and query task info.
- Prompts for tryon cloth.
Quick Start
-
apply for HeyBeauty API Key
-
add the server config to MCP Client config file
{
"mcpServers": {
"heybeauty-mcp": {
"command": "npx",
"args": ["-y", "heybeauty-mcp"],
"env": {
"HEYBEAUTY_API_KEY": "your_heybeauty_api_key"
}
}
}
}
Resources
- List and access clothes via
cloth://URIs - Each cloth has a id, name, description, image url and metadata
- Plain text mime type for simple content access
Tools
submit_tryon_task- Submit a tryon task- Takes user image url, cloth image url, cloth id and cloth description as required parameters
- Stores tryon task in server state
query_tryon_task- Query a tryon task- Takes task id as required parameter
- Returns tryon task info
Prompts
tryon_cloth- Tryon cloth- Takes user image url, cloth image url, cloth id and cloth description as required parameters
- Returns structured prompt for LLM tryon
Resources
cloth://- URI for clothes- Each cloth has a id, name, description, image url and metadata
Development
Install dependencies:
npm install
Build the server:
npm run build
For development with auto-rebuild:
npm run watch
Installation
To use with Claude Desktop, add the server config:
On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"heybeauty-mcp": {
"command": "node",
"args": ["/path/to/heybeauty-mcp/build/index.js"]
},
"env": {
"HEYBEAUTY_API_KEY": "your_heybeauty_api_key"
}
}
}
Follow this document to get HeyBeauty API Key.
Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:
npm run inspector
The Inspector will provide a URL to access debugging tools in your browser.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.