# 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.

[![npm version](https://img.shields.io/npm/v/@noteboxd/mcp?color=2b54d4)](https://www.npmjs.com/package/@noteboxd/mcp)
[![license](https://img.shields.io/npm/l/@noteboxd/mcp?color=2b54d4)](./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

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000000)](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)