# CellarTracker MCP

> **Disclaimer:** This is a community-maintained project with no affiliation to, or endorsement by, CellarTracker! LLC. It uses CellarTracker's self-serve [data export](https://support.cellartracker.com/article/29-exporting-data) on your own account's behalf.

Connect Claude to your [CellarTracker](https://www.cellartracker.com/) wine cellar. Query your inventory, get drinking recommendations, and analyze purchases and drinking history, all through natural conversation. No need to refresh your inventory, or share your tasting notes. Claude pulls them directly from your CellarTracker account.

## Install

Two install methods for different Claude interfaces. You may need one or both:

| | Desktop Extension (.mcpb) | Claude Code Plugin |
|---|---|---|
| **Works in** | Chat (Desktop), Cowork | Cowork, Code |
| **Tools** | 11 cellar tools | All 13 tools (includes `setup-credentials` and `clear-user-data`) |
| **Skills** | No | Yes |
| **Setup** | One-click download | Marketplace or CLI |
| **Credentials** | Prompted on install, stored in OS keychain | Run `setup-credentials` after install |

**Which do I need?**

- **Chat (Desktop) only** → Desktop Extension
- **Code only** → Claude Code Plugin
- **Cowork only** → Either works (plugin adds skills)
- **Full coverage** → Install both

Installing both is safe. The extension covers Chat (Desktop); the plugin covers Cowork and Code. In Cowork, both are accessible without conflict. Note, there is no coverage for claude.ai web chat sessions.

### Desktop Extension (Chat & Cowork)

One-click install. No terminal needed.

1. Download `cellartracker-mcp.mcpb` from the [latest release](https://github.com/slavins-co/cellartracker-mcp/releases/latest)
2. Double-click the file to install in Claude Desktop
3. Enter your CellarTracker username and password when prompted
4. Start chatting (e.g. *"What wines should I open this month?"*)

Credentials are stored in your OS keychain (macOS Keychain / Windows Credential Manager). To update them later, go to Customize > Connectors > CellarTracker.

### Claude Code Plugin (Cowork & Code)

Full experience with tools **and** skills.

#### Via Desktop app

1. Open the Code tab > Customize > Browse plugins > Personal > **+** > Add marketplace from GitHub > enter `slavins-co/cellartracker-mcp`
2. Find "CellarTracker MCP" in the plugin browser and click **Install**
3. **Set up credentials immediately**: In a new Code or Cowork session, say *"Set up my CellarTracker credentials"*

#### Via terminal

**Step 1:** Add the marketplace
```
/plugin marketplace add slavins-co/cellartracker-mcp
```

**Step 2:** Install the plugin
```
/plugin install cellartracker-mcp@cellartracker-mcp
```

**Step 3:** Set up credentials immediately — say:
> *"Set up my CellarTracker credentials"*

Claude will verify and save them. No restart needed. Without credentials, tools will return errors and skills won't have data to work with.

**Alternative:** Set `CT_USERNAME` and `CT_PASSWORD` as environment variables in your shell profile.

Credentials are stored only on your machine. When using the setup tool, they pass through Anthropic's servers as part of the conversation. They are sent to CellarTracker's servers for authentication.

## What you can do

| Tool | What it does |
|------|-------------|
| `setup-credentials` | Connect your CellarTracker account (Claude Code plugin only — Desktop Extension handles credentials during install) |
| `search-cellar` | Find wines by name, color, region, varietal, location, or vintage |
| `drinking-recommendations` | Wines to open now, sorted by drinking window urgency |
| `cellar-stats` | Collection overview — totals and breakdowns by any dimension |
| `purchase-history` | Spending analysis by store, date range, or wine |
| `recent-deliveries` | Wines actually received in a date range, by delivery date (not order date) |
| `incoming-orders` | Wines ordered but not yet received — what's on the way |
| `get-wishlist` | Your wishlist with notes on why each wine was added and a max price |
| `consumption-history` | Wines you've opened — by name, color, or date range |
| `tasting-notes` | Your tasting notes and reviews with ratings and scores |
| `bottle-details` | Find individual bottles by name, location, bin, size, or barcode — cellar and consumed |
| `refresh-data` | Force a fresh pull (auto-refreshes every 24 hours) |
| `clear-user-data` | Remove stored credentials and cached data from this machine (Claude Code plugin only) |

Every tool returns structured JSON alongside its readable text, so clients can compute over results directly. List tools support `offset` pagination past the 25-per-page cap.

### Resources

For bulk analysis without per-tool result caps, the server also exposes the cached table exports as MCP resources: `cellartracker://tables/<Table>` (raw CSV, one per table — List, Notes, Purchase, Consumed, Availability, Tag, Bottles, Pending) and `cellartracker://meta/cache` (JSON freshness timestamps per table plus the server version, readable without credentials).

## Included skills

> **Note:** Skills are available in Cowork and Code modes via the Claude Code plugin. Chat mode (Desktop Extension) provides tools only.

**cellartracker-data** — Teaches Claude to interpret CellarTracker data: table relationships, score abbreviations, drinking windows, and query routing.

**wine-purchase-evaluator** — Framework for evaluating wine purchases. Two-score system (Quality + Personal Fit) with BUY/CONSIDER/PASS verdicts. Checks your cellar for redundancy, verifies pricing, and applies drinking window discipline.

To customize the evaluator for your preferences, copy `skills/wine-purchase-evaluator/references/preferences-example.md` to `preferences.md` in the same directory and edit it.

## How it works

CellarTracker has no official API. This server uses their [CSV export endpoint](https://support.cellartracker.com/article/29-exporting-data), which authenticates with your username and password over HTTPS. Data is cached locally and auto-refreshes every 24 hours.

The server can only access **your** data — inventory, purchases, notes, and wishlist. It cannot search CellarTracker's full wine database.

## Security & credentials

### CellarTracker API limitations

CellarTracker has no OAuth, API keys, or scoped tokens. Authentication requires your actual account username and password, sent as URL query parameters over HTTPS. While encrypted on the wire, query parameters are routinely logged in server-side access logs on CellarTracker's infrastructure. There is no way to create read-only or limited-access credentials, therefore, this MCP only performs read operations, but it authenticates with your full account.

### How this server protects your credentials

| Protection | Details |
|---|---|
| **File permissions** | Config directory `0700`, `.env` file `0600` — only your OS user can read |
| **Error stripping** | Network errors are caught and re-thrown without the URL, which contains credentials |
| **No logging** | Credentials never appear in stdout, stderr, or error messages |
| **OS keychain** | Desktop Extension (`.mcpb`) stores credentials in macOS Keychain / Windows Credential Manager |
| **Env var support** | Set `CT_USERNAME` / `CT_PASSWORD` environment variables to avoid storing credentials on disk |

The Claude Code plugin stores credentials as plaintext in `~/.config/cellartracker-mcp/.env`. We evaluated OS keychain integration ([#22](https://github.com/slavins-co/cellartracker-mcp/issues/22)) and decided against it. The native dependency cost (`node-gyp` / `keytar`) outweighs the security benefit for wine cellar data, and the Desktop Extension path already uses the OS keychain.

### Recommendations

- **Use a unique password** for CellarTracker. Do not reuse a password from other services.
- **Prefer environment variables** over the `setup-credentials` tool if you want to avoid persisting credentials to disk.
- **Pin to a specific version** in your MCP config (e.g., `cellartracker-mcp@0.5.0`) rather than relying on `@latest`.

## Development

For contributors or anyone who wants to run from source:

```bash
git clone https://github.com/slavins-co/cellartracker-mcp.git
cd cellartracker-mcp
npm install
npm run build

# Set credentials
cp .env.example .env
# Edit .env with your CT login

# Test as Claude Code plugin
claude --plugin-dir .
```

### npx local-resolution footgun

If you run `npx -y cellartracker-mcp` (e.g. via an MCP client config) with your working directory inside a local checkout of this repo, npm can resolve the bare package name to that local folder instead of downloading it from the registry — so whatever is on disk in `dist/` gets served, not the published version. `npm install`/`npm ci` now runs a `prepare` script that rebuilds `dist/` automatically, so a fresh clone is always current. But if you edit `src/` directly and don't run `npm install` or `npm run build` again, `dist/` will silently go stale — the server keeps running the old compiled code with no error. If output looks wrong while developing, rebuild (`npm run build`) before assuming the bug is in `src/`.

## AI Disclosure

This project was developed with AI assistance.

## Trademark Disclosure

This project is in no way affiliated or connected to CellarTracker! LLC. "CellarTracker" is a trademark of CellarTracker! LLC. 

## License

MIT