Noteboxd Fragrance & Perfume MCP
A Model Context Protocol server (and API) for fragrance and perfume data. Connect Claude, ChatGPT, Cursor, or any MCP client to the Noteboxd fragrance encyclopedia: fragrances, notes, accords, brands, perfumers, community reviews, and charts.
Once connected, you can ask things like:
- "I own Oud Wood and Aventus. What else should I try for cold-weather formal wear?"
- "Compare Bleu de Chanel and Dior Sauvage."
- "What are reviewers saying about Baccarat Rouge 540?"
The assistant answers from Noteboxd's data instead of guessing.
Quickstart
- Create an API key at developers.noteboxd.com. The free tier is 50 calls/day and needs no card.
- Add the server to your MCP client (see below).
- Ask your assistant about fragrance.
NOTEBOXD_API_KEY=nb_live_your_key npx -y @noteboxd/mcp
Install
Every client uses the same command (npx -y @noteboxd/mcp) with your key in NOTEBOXD_API_KEY.
Claude Desktop / Claude Code
Add to claude_desktop_config.json:
{
"mcpServers": {
"noteboxd": {
"command": "npx",
"args": ["-y", "@noteboxd/mcp"],
"env": { "NOTEBOXD_API_KEY": "nb_live_your_key" }
}
}
}
Cursor
Then set your real key. Or add the JSON block above to ~/.cursor/mcp.json.
VS Code
{
"servers": {
"noteboxd": {
"command": "npx",
"args": ["-y", "@noteboxd/mcp"],
"env": { "NOTEBOXD_API_KEY": "nb_live_your_key" }
}
}
}
Hosted alternative
Noteboxd also runs a hosted MCP server at https://mcp.noteboxd.com/mcp (Streamable HTTP, with
OAuth sign-in) if you would rather not run anything locally. This package is the local,
open-source option.
Tools
All tools are read-only and return JSON. Each call is authenticated with your key and counts against your Noteboxd developer plan (the free tier covers 50 calls/day).
Search and discovery
| Tool | Description |
|---|---|
search | Search across fragrances, brands, notes, perfumers, collections |
search_fragrances | Filter fragrances by query, brand, note, family, or price range |
trending | Trending searches and most-worn fragrances |
list_charts, get_chart | Chart rankings and leaderboards |
Fragrances
| Tool | Description |
|---|---|
get_fragrance | Full profile: notes, accords, perfumer, community score |
get_fragrance_reviews | Paginated community reviews |
get_similar_fragrances | Fragrances with a similar accord profile |
get_wearing_stats | Wearing counts over recent windows |
compare_fragrances | Two fragrances compared side by side |
get_review_digest | Short summary of a fragrance's reviews |
batch_get_fragrances | Up to 50 fragrances by id in one call |
enrich_fragrance | Profile plus notes, accords, reviews, and similar in one call |
Brands, perfumers, notes
| Tool | Description |
|---|---|
get_brand, list_brand_fragrances | Brand profile and catalogue |
get_perfumer | Perfumer profile and top creations |
list_notes, get_note | Browse notes and single-note profiles |
list_accords | List accord families |
Configuration
| Variable | Required | Description |
|---|---|---|
NOTEBOXD_API_KEY | yes | Your nb_live_ key from developers.noteboxd.com |
NOTEBOXD_API_BASE_URL | no | Override the API origin (default https://api.noteboxd.com) |
You can also pass the key with --api-key nb_live_....
How it works
This is a thin local server. It speaks MCP to your client over stdio and forwards each tool call
to api.noteboxd.com/v1 using your key. It stores no data and holds no credentials beyond the key
you provide.
AI client --stdio--> noteboxd-mcp --HTTPS + your key--> api.noteboxd.com/v1
Examples
See examples/ for runnable code: curl, TypeScript, and Python.
Pricing
The server is free and open source. API usage follows your Noteboxd developer plan: a free tier (50 calls/day), then pay-as-you-go per call. Most reads are $0.01; the AI tools cost a few cents. See developers.noteboxd.com/#pricing.