@noteboxd/mcp

Noteboxd MCP

A Model Context Protocol server that lets an AI assistant (Claude, ChatGPT, Cursor, and other MCP clients) query 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.

License

MIT