Skincare Recommendation MCP Server

An MCP (Model Context Protocol) server that helps recommend skincare products based on a client's skin type and concerns, checks for known ingredient conflicts with their current routine, and looks up stock/pricing or alternatives from a simulated store inventory.

Built for the "Uso de un protocolo existente" project (CC3067 Redes, Universidad del Valle de Guatemala). Runs locally over stdio — no network access, no API keys required.

Features

• Search a product catalog by skin type and/or skincare concern

• Look up full details (price, stock, active ingredients) for a specific product

• Find in-stock alternatives that share an active ingredient with an out-of-stock or discontinued product

• Check whether a candidate product's active ingredients conflict with a client's current routine, using a rule set based on real dermatological interactions (e.g. retinol + AHA acids, benzoyl peroxide + tretinoin)

• End-to-end recommendation: filter the catalog by skin type/concerns and flag conflicts against the current routine in one call

Related MCP server: Skincare-MCP

Requirements

• uv (manages the Python version and dependencies — nothing else to install manually)

• Docker — only needed to run the remote (HTTP) transport in a container

Installation

git clone <https://github.com/AleWWH1104/skincare-mcp-server.git>
cd skincare-mcp-server
uv sync

uv sync reads pyproject.toml/uv.lock and creates an isolated .venv with the exact dependency versions this server was built and tested against.

Running it standalone (for testing)

Use the official MCP Inspector to call each tool by hand from a web UI, without needing an LLM host:

npx @modelcontextprotocol/inspector uv run python server.py

Connecting it to an MCP host

This server ships two transport adapters over the same tool logic (mcp_protocol.py) — a local one and a remote one.

Local (stdio)

uv run --directory /absolute/path/to/skincare-mcp-server python server.py

Example host-side config entry (Python, matching this project's own host):

MCPServerConfig(
    name="skincare",
    command="uv",
    args=["run", "--directory", "/absolute/path/to/skincare-mcp-server", "python", "server.py"],
)

Remote (Streamable HTTP, via Docker)

http_server.py exposes the same tools over a single HTTP endpoint using the MCP "Streamable HTTP" transport (one POST /mcp per JSON-RPC message), implemented by hand with only the standard library — no MCP SDK, no web framework.

Build and run the container:

docker build -t skincare-mcp-server .
docker run --rm -p 8080:8080 skincare-mcp-server

The server listens on PORT (default 8080), so it's ready to deploy to any container-based cloud service (Cloud Run, Fly.io, Render, etc.) that sets PORT for you.

Example host-side config entry for the remote transport:

MCPServerConfig(
    name="skincare_remote",
    transport="http",
    url="http://localhost:8080/mcp",
)

Data model

Several tools return a Product object:

Tools

search_products

Search the catalog by skin type and/or concern.

Parameters

Returns: Product[]

Example

{ "skin_type": "grasa", "concern": "acné" }

[
    { "id": "cl-001", "name": "Gel Limpiador Purificante", "brand": "DermaPura", "stock": 14, "...": "..." },
    { "id": "sr-001", "name": "Sérum Niacinamida 10%", "brand": "PureLab", "stock": 9, "...": "..." }
]

get_product_details

Full details for one product by id.

Parameters

Returns: Product, or {"error": "..."} if the id doesn't exist.

Example

{ "product_id": "sr-001" }

{
    "id": "sr-001",
    "name": "Sérum Niacinamida 10%",
    "brand": "PureLab",
    "price": 145.0,
    "stock": 9,
    "active_ingredients": ["niacinamida"]
}

find_alternatives

Other in-stock products sharing at least one active ingredient with the given product — for when it's out of stock or the client wants a different brand.

Parameters

Returns: Product[]

Example — sr-002 (a vitamin C serum) is out of stock:

{ "product_id": "sr-002" }

[{ "id": "sr-006", "name": "Sérum Vitamina C 10% Suave", "brand": "GlowCo", "stock": 10 }]

check_ingredient_conflicts

Check a candidate product's active ingredients against ingredients the client is already using.

Parameters

Returns: array of conflicts, empty if none found:

[
    {
        "ingredients": ["retinol", "ácido glicólico"],
        "severity": "avoid",
        "reason": "Combining retinol with AHA exfoliants in the same routine significantly increases the risk of irritation, dryness and peeling.",
        "recommendation": "Alternate nights: retinol one night, AHA/BHA exfoliant the next, never the same day."
    }
]

Example call

{ "current_ingredients": ["retinol"], "candidate_ingredients": ["ácido glicólico"] }

recommend_products

End-to-end recommendation: filter the catalog by skin type/concerns, and flag conflicts against the client's current routine for every match.

Parameters

Returns

{
    "recommendations": [
        {
            "product": { "id": "sr-001", "name": "Sérum Niacinamida 10%", "...": "..." },
            "conflicts": [],
            "safe_to_combine": true
        },
        {
            "product": { "id": "tr-002", "name": "Exfoliante Químico AHA/BHA", "...": "..." },
            "conflicts": [{ "severity": "caution", "...": "..." }],
            "safe_to_combine": false
        }
    ]
}

Notes

• The product catalog (data/inventory.json) is simulated data for this project, not a real store.

• The ingredient interaction rules (data/ingredient_rules.json) are simplified from real, commonly cited dermatological guidance (e.g. retinol/AHA, benzoyl peroxide/tretinoin). This is a demo tool, not medical or professional skincare advice.