Fragrance & Perfume MCP (Noteboxd)
Fragrance & perfume MCP: search fragrances, notes, accords, brands, perfumers, reviews & charts.
Open source Repository Open in the app JSON README (API)
About
Fragrance & perfume MCP: search fragrances, notes, accords, brands, perfumers, reviews & charts.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.noteboxd
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.4
- Stars
- 1
- Last push
- 2026-07-31T18:17:25Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:17
- Updated
- 2026-08-29 03:01:17
- Origin id
com.noteboxd/mcp
README
# Noteboxd Fragrance & Perfume MCP
A [Model Context Protocol](https://modelcontextprotocol.io) server (and API) for **fragrance and
perfume** data. Connect Claude, ChatGPT, Cursor, or any MCP client to the
[Noteboxd](https://www.noteboxd.com) fragrance encyclopedia: fragrances, notes, accords, brands,
perfumers, community reviews, and charts.
[](https://www.npmjs.com/package/@noteboxd/mcp)
[](./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](https://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.
```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`:
```json
{
"mcpServers": {
"noteboxd": {
"command": "npx",
"args": ["-y", "@noteboxd/mcp"],
"env": { "NOTEBOXD_API_KEY": "nb_live_your_key" }
}
}
}
```
### Cursor
[](cursor://anysphere.cursor-deeplink/mcp/install?name=noteboxd&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBub3RlYm94ZC9tY3AiXSwiZW52Ijp7Ik5PVEVCT1hEX0FQSV9LRVkiOiJuYl9saXZlX1lPVVJfS0VZIn19)
Then set your real key. Or add the JSON block above to `~/.cursor/mcp.json`.
### VS Code
```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](https://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/`](./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](https://developers.noteboxd.com/#pricing).
## License
[MIT](./LICENSE)