HeyBeauty 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.

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

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" } } }

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.