Noteboxd MCP server
✓ VerifiedConnects AI clients to a fragrance encyclopedia to search for perfumes, notes, brands, perfumers, and community reviews.
Also known as noteboxd/mcp, mcp, @noteboxd/mcp
- Stars
- 1
- Tools
- 13
- Downloads, 30 days
- —
- Latest version
- 0.1.4
- Last commit
- Jul 31, 2026
- License
- MIT
What is Noteboxd MCP?
Noteboxd connects AI clients to a fragrance encyclopedia to search for perfumes, notes, brands, perfumers, and community reviews. It exposes 13 tools, such as search, search_fragrances, trending.
Summary generated from the project's README
About Noteboxd MCP server
Accessing a detailed fragrance encyclopedia from within AI clients like Claude, ChatGPT, or Cursor allows users to move beyond AI guesswork when discussing scents. This server connects your assistant to the Noteboxd database, providing factual information about perfumes, brands, perfumers, and specific scent notes. It is designed for fragrance enthusiasts and developers who want to integrate community reviews and scent profiles directly into their conversational workflows.
You can run this server locally using npx or connect via a hosted HTTP option. To use the local version, you must provide a NOTEBOXD_API_KEY. The free tier allows for 50 calls per day without requiring a credit card. The server provides a wide range of read-only tools, including search_fragrances for filtering by price or family, compare_fragrances for side-by-side analysis, and get_review_digest to quickly understand community sentiment. It also offers specialized functions like get_similar_fragrances and get_wearing_stats to help discover new scents based on existing collections.
What you can do with it
- 1Discovering new scent recommendationsAsk your AI to suggest new perfumes based on the specific scents you already own.
- 2Comparing different perfume profilesRequest a side-by-side comparison of two specific fragrances to see how they differ.
- 3Analyzing community sentimentGet a summary of what actual users are saying about a particular fragrance.
- 4Exploring fragrance ingredientsSearch for specific notes or accords to understand the composition of a perfume.
Written from the project's README. Every use case is checked against a quote from it.
How to install Noteboxd MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Noteboxd MCP in Claude Code
$ claude mcp add --env 'NOTEBOXD_API_KEY=<YOUR_NOTEBOXD_API_KEY>' mcp -- npx -y @noteboxd/mcpInstall Noteboxd MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@noteboxd/mcp"
],
"env": {
"NOTEBOXD_API_KEY": "<YOUR_NOTEBOXD_API_KEY>"
}
}
}
}Install Noteboxd MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@noteboxd/mcp"
],
"env": {
"NOTEBOXD_API_KEY": "<YOUR_NOTEBOXD_API_KEY>"
}
}
}
}Install Noteboxd MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@noteboxd/mcp"],"env":{"NOTEBOXD_API_KEY":"<YOUR_NOTEBOXD_API_KEY>"}}'Install Noteboxd MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@noteboxd/mcp"
],
"env": {
"NOTEBOXD_API_KEY": "<YOUR_NOTEBOXD_API_KEY>"
}
}
}
}Install Noteboxd MCP in Codex
$ codex mcp add mcp --env 'NOTEBOXD_API_KEY=<YOUR_NOTEBOXD_API_KEY>' -- npx -y @noteboxd/mcpInstall Noteboxd MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@noteboxd/mcp"] [mcp_servers.mcp.env] NOTEBOXD_API_KEY = "<YOUR_NOTEBOXD_API_KEY>"
Install Noteboxd MCP in Gemini CLI
$ gemini mcp add -s user -e 'NOTEBOXD_API_KEY=<YOUR_NOTEBOXD_API_KEY>' mcp npx -- -y @noteboxd/mcpInstall Noteboxd MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@noteboxd/mcp"
],
"env": {
"NOTEBOXD_API_KEY": "<YOUR_NOTEBOXD_API_KEY>"
}
}
}
}Noteboxd MCP tools 13
Detected from the READMEsearchsearch_fragrancestrendingget_fragranceget_fragrance_reviewsget_similar_fragrancesget_wearing_statscompare_fragrancesget_review_digestbatch_get_fragrancesenrich_fragranceget_perfumer
| search | — | |
| search_fragrances | — | |
| trending | — | |
| get_fragrance | — | |
| get_fragrance_reviews | — | |
| get_similar_fragrances | — | |
| get_wearing_stats | — | |
| compare_fragrances | — | |
| get_review_digest | — | |
| batch_get_fragrances | — | |
| enrich_fragrance | — | |
| get_perfumer | — |
Show all 13 toolsShow fewer tools
list_accords
| list_accords | — |
Configuration
NOTEBOXD_API_KEYRequiredSecretNoteboxd API key (nb_live_...). Create one free at https://developers.noteboxd.com
| Name | Description | |
|---|---|---|
| NOTEBOXD_API_KEY | Noteboxd API key (nb_live_...). Create one free at https://developers.noteboxd.com | RequiredSecret |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablenoteboxd/mcp is public and reachablegithub.com/noteboxd/mcp ↗Pass
- Package names this repository as its source@noteboxd/mcp names noteboxd/mcp as sourcenpmjs.com/package/@noteboxd/mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-31github.com/noteboxd/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @noteboxd/mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 781 msPass
README
View on GitHubNoteboxd 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.
License
Noteboxd MCP questions
How do I add Noteboxd MCP to Claude Code?
Run claude mcp add --env 'NOTEBOXD_API_KEY=<YOUR_NOTEBOXD_API_KEY>' mcp -- npx -y @noteboxd/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Noteboxd MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Noteboxd MCP provide?
It exposes 13 tools, including search, search_fragrances, trending, get_fragrance, get_fragrance_reviews.
How much does it cost to use the Noteboxd MCP?
The server is free and open source, but API usage depends on your Noteboxd developer plan, which includes a free tier of 50 calls per day.
Can I use the server without running it locally?
Yes, Noteboxd offers a hosted MCP server at mcp.noteboxd.com that uses OAuth sign-in.