Perfume Picks

Official8 tools

by bguillow-rgb · TypeScript

Search the Perfume Picks fragrance database: 13,000+ scents with notes, dupes, and wear data.

Perfume Picks MCP Server (io.github.bguillow-rgb/perfume-picks)

This MCP server provides read-only access to the Perfume Picks fragrance database. It supports querying a catalog of 13,000+ scents, including notes, dupes, and community wear data, via MCP-compatible AI clients such as Claude.

🛠️ Key Features

Read-only access to 13,000+ fragrances
Full note pyramids, accords, and curated dupes
Community wear data included in records
8 tools available in the server

🚀 Use Cases

Searching fragrances by brand, family, gender, and MSRP filters
Retrieving a full record for one scent

⚡ Developer Benefits

search_fragrances: full-text catalog search using filters
get_fragrance: returns the full record for a scent
Designed for MCP-compatible AI clients

⚠️ Limitations

Database access is described as read-only
Documentation excerpt lists only two tools in the tool table

Topics

agent-toolsai-agentsfragrancemcpmcp-servermodel-context-protocolperfumerecommendationsgemini-cli-extension

Captured live from the server via tools/list.

search_fragrances

Full-text search across 13,000+ fragrances in the Perfume Picks database. Filter by brand, fragrance family, gender, and MSRP (USD). Returns note pyramids, accords, and community wear scores with source attribution.

Parameters7

query	string	optional	Free-text search: fragrance or brand name
brand	string	optional	Brand name filter, e.g. 'Dior'
fragrance_family	string	optional	Family filter, e.g. 'woody', 'amber', 'fresh'
gender	string	optional	Marketed gender category of the fragrance; omit to include all
price_min	number	optional	Minimum MSRP in USD
price_max	number	optional	Maximum MSRP in USD
limit	integer	optional	Max results (default 10, max 10)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 120,
      "description": "Free-text search: fragrance or brand name"
    },
    "brand": {
      "type": "string",
      "maxLength": 200,
      "description": "Brand name filter, e.g. 'Dior'"
    },
    "fragrance_family": {
      "type": "string",
      "maxLength": 120,
      "description": "Family filter, e.g. 'woody', 'amber', 'fresh'"
    },
    "gender": {
      "type": "string",
      "enum": [
        "masculine",
        "feminine",
        "unisex"
      ],
      "description": "Marketed gender category of the fragrance; omit to include all"
    },
    "price_min": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum MSRP in USD"
    },
    "price_max": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum MSRP in USD"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 10, max 10)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_fragrance

Detailed record for one fragrance: full note pyramid (top/heart/base), accords, concentration, community longevity/sillage/compliment scores, and MSRP. Accepts a Perfume Picks slug or a name like 'Bleu de Chanel'.

Parameters1

slug_or_name

string

required

Fragrance slug or name

Raw schema

{
  "type": "object",
  "properties": {
    "slug_or_name": {
      "type": "string",
      "maxLength": 200,
      "description": "Fragrance slug or name"
    }
  },
  "required": [
    "slug_or_name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_dupes

Curated dupes for a fragrance — cheaper scents documented to smell like the original, with match percentage and price comparison. The answer to 'what smells like X without the price tag'.

Parameters1

fragrance

string

required

Fragrance slug or name to find dupes for

Raw schema

{
  "type": "object",
  "properties": {
    "fragrance": {
      "type": "string",
      "maxLength": 200,
      "description": "Fragrance slug or name to find dupes for"
    }
  },
  "required": [
    "fragrance"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

find_similar

Fragrances most similar to a given one, from Perfume Picks' precomputed similarity ranking over notes and accords.

Parameters2

fragrance	string	required	Fragrance slug or name
limit	integer	optional	Max results (default 5)

Raw schema

{
  "type": "object",
  "properties": {
    "fragrance": {
      "type": "string",
      "maxLength": 200,
      "description": "Fragrance slug or name"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "fragrance"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_recommendations

Personalized fragrance picks from note/accord preferences (e.g. 'vanilla', 'oud', 'citrus'), a budget in USD, an occasion ('office', 'date night', 'gift', 'signature scent'), and gender presentation.

Parameters5

preferences	array	required	Notes or accords the wearer enjoys, e.g. ['vanilla','amber','rose']
budget	number	optional	Max MSRP in USD
occasion	string	optional	What the fragrance is for
gender	string	optional	Marketed gender category of the fragrance; omit to include all
limit	integer	optional	Max results (default 5)

Raw schema

{
  "type": "object",
  "properties": {
    "preferences": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      },
      "minItems": 1,
      "maxItems": 20,
      "description": "Notes or accords the wearer enjoys, e.g. ['vanilla','amber','rose']"
    },
    "budget": {
      "type": "number",
      "minimum": 0,
      "description": "Max MSRP in USD"
    },
    "occasion": {
      "type": "string",
      "maxLength": 120,
      "description": "What the fragrance is for"
    },
    "gender": {
      "type": "string",
      "enum": [
        "masculine",
        "feminine",
        "unisex"
      ],
      "description": "Marketed gender category of the fragrance; omit to include all"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 5)"
    }
  },
  "required": [
    "preferences"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compare_fragrances

Side-by-side comparison: note pyramids, shared and distinct accords, longevity/sillage/compliment scores, concentration, and price difference.

Parameters2

fragrance_a	string	required	First fragrance — slug or name
fragrance_b	string	required	Second fragrance — slug or name

Raw schema

{
  "type": "object",
  "properties": {
    "fragrance_a": {
      "type": "string",
      "maxLength": 200,
      "description": "First fragrance — slug or name"
    },
    "fragrance_b": {
      "type": "string",
      "maxLength": 200,
      "description": "Second fragrance — slug or name"
    }
  },
  "required": [
    "fragrance_a",
    "fragrance_b"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

trending_fragrances

Fragrances Perfume Picks users are adding to their wardrobes most over the last 30 days (falls back to catalog popularity when live activity data is unavailable). The method used is labeled in the response.

Parameters1

limit

integer

optional

Max results (default 10, max 10)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Max results (default 10, max 10)"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

what_to_wear_tonight

A fragrance suggestion for right now, based on mood, occasion (e.g. 'date', 'office tomorrow', 'night out', 'cozy evening in'), and season — scored with Perfume Picks' community compliment, office-safety, and versatility data.

Parameters4

mood	string	optional	How you're feeling
occasion	string	optional	The setting
season	string	optional	Season to weight the pick toward — heavier, warmer scents in winter; fresher in summer
gender	string	optional	Marketed gender category of the fragrance; omit to include all

Raw schema

{
  "type": "object",
  "properties": {
    "mood": {
      "type": "string",
      "maxLength": 120,
      "description": "How you're feeling"
    },
    "occasion": {
      "type": "string",
      "maxLength": 120,
      "description": "The setting"
    },
    "season": {
      "type": "string",
      "enum": [
        "winter",
        "spring",
        "summer",
        "fall"
      ],
      "description": "Season to weight the pick toward — heavier, warmer scents in winter; fresher in summer"
    },
    "gender": {
      "type": "string",
      "enum": [
        "masculine",
        "feminine",
        "unisex"
      ],
      "description": "Marketed gender category of the fragrance; omit to include all"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md5 KBView on GitHub

Perfume Picks MCP Server

Query the Perfume Picks fragrance database from Claude, or any MCP-compatible AI client. Read-only access to 13,000+ fragrances with full note pyramids, accords, curated dupes, and community wear data.

Perfume Picks is the Fragrance DNA and collection journal for iOS — get it on the App Store.

Tools

Tool	What it does
`search_fragrances`	Full-text catalog search with brand, family, gender, and MSRP filters
`get_fragrance`	Full record for one scent (by slug or name): note pyramid, accords, community scores
`find_dupes`	Curated cheaper smell-alikes with match percentage — "what smells like X without the price tag"
`find_similar`	Most-similar fragrances from a precomputed similarity ranking
`get_recommendations`	Picks from note/accord preferences + budget + occasion + gender
`compare_fragrances`	Side-by-side: notes, shared/distinct accords, scores, price delta
`trending_fragrances`	What Perfume Picks users are adding to their wardrobes right now
`what_to_wear_tonight`	A scent for right now — date-night picks use community compliment data, office picks use office-safety scores

Every response includes source attribution, a citation-ready summary line, links, and data freshness dates. All scoring is deterministic — no AI calls happen inside the server. All tools are annotated read-only/idempotent.

Install (Claude Desktop)

Requires Node.js 18+.

Add to your claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):

json

{
  "mcpServers": {
    "perfume-picks": {
      "command": "npx",
      "args": ["-y", "perfume-picks-mcp"]
    }
  }
}

Restart Claude Desktop. No API key or configuration needed — the server ships with public read-only access.

Configuration (optional)

Environment variables override the defaults (explicit env vars only — this package never reads .env files):

Variable	Purpose
`SUPABASE_URL`	Override the database URL
`SUPABASE_SERVICE_ROLE_KEY`	Internal use only — unlocks live 30-day wardrobe-add trending. Never distribute this key.

Without the service key, trending_fragrances falls back to catalog popularity and labels the method in its response.

Remote endpoint (no install)

Streamable HTTP for web agents and MCP clients that take a URL:

code

https://jdkwlwyysgofljkobpmr.supabase.co/functions/v1/mcp

Also listed on Smithery and the official MCP registry as io.github.bguillow-rgb/perfume-picks.

Example agent requests

Questions an agent can answer with these tools:

"What smells like Baccarat Rouge 540 without the price tag?" → find_dupes (curated dupes with match %, e.g. Lattafa Ana Abiyedh Rouge, 90%)
"Recommend a fragrance for a summer wedding." → get_recommendations with occasion: "wedding"
"What fragrances have bergamot, vanilla, and amber?" → get_recommendations with those notes as preferences
"What perfume is similar to Bleu de Chanel?" → find_similar
"What should I wear on a date tonight?" → what_to_wear_tonight (scored by community compliment data)
"Compare Sauvage and Bleu de Chanel." → compare_fragrances

Example response shape (truncated):

json

{
  "dupes": [
    { "name": "Lattafa Ana Abiyedh Rouge", "match_pct": 90,
      "savings_usd": 200.0, "msrp_usd": 39.99 }
  ],
  "attribution": {
    "source": "Perfume Picks — Fragrance DNA & Collection Journal",
    "links": { "website": "https://perfumepicks.app/" }
  }
}

Development

bash

npm install
npm run dev     # run from TypeScript via tsx
npm run build   # compile to dist/
npm start       # run compiled server

The server speaks MCP over stdio. Catalog access is read-only by construction: every query path issues SELECTs against tables that are publicly readable under row-level security, and it is rate-limited to 60 calls/minute.

Usage telemetry: each tool call logs the tool name, its arguments, client name/version, duration, and success/failure to a write-only log table (insert-only under RLS; contents are not publicly readable; purged after 90 days). No user identity, account data, or conversation content is collected. Logging is fire-and-forget and never affects responses.

Data & attribution

Fragrance data, note pyramids, dupe matches, and community scores are curated by Perfume Picks. Quote freely with attribution:

Source: Perfume Picks — Fragrance DNA & Collection Journal (perfumepicks.app)

Freshness dates on each fragrance reflect the last data update.

Install

Tools (8)

search_fragrancesget_fragrancefind_dupesfind_similarget_recommendationscompare_fragrancestrending_fragranceswhat_to_wear_tonight

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "perfume-picks": {
      "command": "npx",
      "args": [
        "-y",
        "perfume-picks-mcp@1.0.2"
      ]
    }
  }
}

Perfume Picks MCP Server (io.github.bguillow-rgb/perfume-picks)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

search_fragrances

get_fragrance

find_dupes

find_similar

get_recommendations

compare_fragrances

trending_fragrances

what_to_wear_tonight

Perfume Picks MCP Server

Tools

Install (Claude Desktop)

Configuration (optional)

Remote endpoint (no install)

Example agent requests

Development

Data & attribution

Install

Related servers