Skincare MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Skincare MCP find products similar to Kiehl's Ultra Facial Cream and check for red flags"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Skincare MCP — Ingredient-Based Recommendation Engine
A custom Model Context Protocol (MCP) server that connects a Python recommendation engine to Claude. Built to explore NLP-based product matching and sequential decision-making for skincare.
What It Does
Exposes two tools to Claude via MCP:
find_similar_products— Vectorizes ingredient lists with TF-IDF and returns the top 5 most similar products by cosine similaritycheck_red_flags— Scans a product's ingredients for known irritants and flags them for sensitive skin users
Related MCP server: BeauticsLab MCP
Architecture
skincare-mcp/
├── mcp_server.py ← MCP interface (exposes tools to Claude)
├── engine.py ← TF-IDF vectorization + cosine similarity
├── processor.py ← Data loading, cleaning, fuzzy name matching
├── generate_user_history.py ← Synthetic RL interaction dataset generator
├── cosmetic_p.csv ← Source dataset, 1884 Sephora products [not committed]
└── user_history.csv ← Generated interaction logs [not committed]Technical Details
TF-IDF Ingredient Embeddings
Treats each product's ingredient list as a text document and vectorizes it with TfidfVectorizer from scikit-learn. Common ingredients like Water are down-weighted automatically while rare, distinctive ingredients receive higher weight. Similarity is computed via cosine similarity with bigram support for multi-word INCI names.
Fuzzy Product Name Matching
Uses thefuzz (Levenshtein distance) to resolve product names in three steps: exact match, partial match, then fuzzy match with a configurable threshold. Queries like "creme de la mer" (missing accent) resolve correctly.
Synthetic User History for Offline RL
Generates a structured interaction dataset to support Offline Reinforcement Learning:
Column | Description |
| Simulated user |
| Step in the user's skincare journey |
| State — skin concern levels (0.0–1.0) |
| Action — product applied at this timestep |
| Reward — skin improvement score at T+1 |
The reward function accounts for product rating, skin type compatibility, and irritant penalties for sensitive users. The dataset structure is compatible with Batch-Constrained Q-learning (BCQ) and similar offline RL algorithms.
Stack
Tool | Purpose |
FastMCP | MCP server framework |
scikit-learn | TF-IDF vectorization, cosine similarity |
thefuzz | Fuzzy string matching |
pandas / numpy | Data processing |
uv | Package management |
Setup
Prerequisites: Python 3.11+, uv
git clone https://github.com/pserein/skincare-mcp.git
cd skincare-mcp
uv sync
# Download cosmetic_p.csv from Kaggle and place it in the project root
# https://www.kaggle.com/datasets/eward96/skincare-products-clean-dataset
.venv/bin/python generate_user_history.pyAdd to claude_desktop_config.json:
{
"mcpServers": {
"skincare-recommender": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/skincare-mcp/mcp_server.py"]
}
}
}Roadmap
MCP server with ingredient-based product similarity
TF-IDF + cosine similarity for NLP-based matching
Fuzzy product name resolution
Synthetic user history dataset (State, Action, Reward)
Offline RL policy (BCQ) trained on user history
Skin-type filtering in similarity search
Resume Description
Developed a custom MCP Server to bridge a Python recommendation engine with Claude. Engineered TF-IDF ingredient embeddings with cosine similarity for NLP-based product matching. Generated a synthetic sequential interaction dataset (State, Action, Reward) to support an Offline Reinforcement Learning policy using Batch-Constrained Q-learning (BCQ).
Available Tools
4 toolscheck_red_flagsB
Check if a product contains known irritants for sensitive skin
Inputs: product_name (required). Returns: result
find_similar_productsB
Find skincare products with similar ingredients using Jaccard similarity
Inputs: product_name (required). Returns: result
query_databaseA
Run a read-only SQL SELECT query against the local skincare SQLite database. The database has a 'products' table with columns: name, brand, Label (category), price, rank, ingredients, Combination, Dry, Normal, Oily, Sensitive (skin type flags, 0 or 1). Only SELECT statements are allowed. Example: SELECT name, brand, price FROM products WHERE Label = 'Moisturizer' AND rank >= 4.5 LIMIT 5
Inputs: sql (required). Returns: result
search_live_productsA
Search Open Beauty Facts for real-time beauty product data. Useful for products not in the local database (e.g. CeraVe, La Roche-Posay). Returns product name, brand, and ingredients for each result. Limited to beauty and personal care products only.
Inputs: query (required), max_results. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: checking irritants, finding similar products via Jaccard similarity, running SQL queries on a local database, and searching an external database. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., check_red_flags, find_similar_products, query_database, search_live_products), making them predictable and easy to parse.
With 4 tools, the set is slightly on the low side but still well-scoped for a skincare-focused MCP covering local and live data, safety checks, and similarity search. Each tool serves a distinct need without redundancy.
The tool surface covers key operations: local query, live search, ingredient safety, and similarity search. Minor gaps like a dedicated product lookup are mitigated by the SQL query tool, but advanced operations (e.g., user profiles or updates) are absent, which is acceptable for a read-only analysis server.
Maintenance
Related MCP Connectors
Australian ingredient scanner MCP — 21k+ AU products, 237 chemical rules, 17 condition tags.
Condition-aware ingredient and product checks for agents, with evidence tiers and citations.
AI-native beauty ads, sponsored product discovery, and brand recommendations.
Decode skincare ingredient labels (1% line, % ranges, what each does) and get US dry skin forecasts.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables semantic search and natural language product recommendations using ChromaDB vector store and Azure OpenAI embeddings. Supports multi-filter search by category, brand, and price with 8 specialized MCP methods for intelligent product discovery.-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to search beauty products from Korean catalogs (Olive Young, Daiso, e-commerce) and analyze personal skincare routines and ingredient compositions via BeauticsLab.-
- AlicenseAqualityCmaintenanceCondition-aware ingredient & product safety intelligence for AI agents. Every answer carries a claim-level evidence attestation, verdict, an evidence tier, and a citation – curated against authoritative sources (LactMed, InfantRisk, PubMed, DSLD, DermNet, EU CosIng) by Health AI. Hosted MCP server – no install, no key. Endpoint: https://mcp.healthai.com (Streamable HTTP, JSON-RPC 29MIT
- AlicenseNot gradedqualityDmaintenanceEnables checking cosmetic ingredient safety and multi-jurisdiction compliance across 12 regulatory bodies, backed by a comprehensive dataset of safety opinions and studies.1MIT