Noteboxd

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.

npm version license

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

1. Create an API key at developers.noteboxd.com. The free tier is 50 calls/day and needs no card.
2. Add the server to your MCP client (see below).
3. 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

Add to 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.

License

MIT