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.

bash

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:

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

config.json

{
  "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.

Code

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.

License

MIT