Pantrist-dev/pantrist-mcp

A Model Context Protocol server that wraps
the Pantrist REST API, so an LLM client (Claude Desktop, the Claude web/mobile
connector, Cursor, …) can manage shopping lists, the pantry, recipes and the
week plan in natural language.
It's a **thin wrapper** — no business logic. Every tool maps to an existing
REST endpoint and forwards the caller's Bearer token. The HTTP client is
**generated from the public OpenAPI spec** (src/generated/pantrist-api.ts),
so request/response types track the API automatically; only the curated tool
layer (src/tools.ts) is hand-written.
Documentation
- **docs/ARCHITECTURE.md** — components, the token context, request flow, transports, regeneration.
- **docs/AUTHENTICATION.md** — OAuth flow, **token-type ↔ tool compatibility**, multi-user isolation, the consent-page dependency.
- **docs/DEPLOYMENT.md** — full env var reference, remote/ingress setup, scaling, security checklist.
- **docs/TOOLS.md** — every tool's args, REST mapping, and the item shape.
- **docs/LIMITATIONS.md** — known rough edges (read before relying on it in production).
Two transports
| Transport | When | Auth |
|---|---|---|
| **stdio** (src/stdio.ts) | Local PoC, single user, Claude Desktop | Bearer from PANTRIST_TOKEN env |
| **Streamable HTTP** (src/http.ts) | Remote, multi-user, the Claude connector | Per-request Bearer, obtained by the client via OAuth |
Connecting Claude to the hosted server
If you just want to **use** Pantrist with Claude (not self-host), the public
endpoint is **https://mcp.pantrist.app/mcp**. Pick whichever Claude surface
you're on; in every case the first tool call walks you through an OAuth login
to your Pantrist account, no token to copy by hand.
Claude.ai (web or desktop app)
1. **claude.ai** → profile menu → **Settings → Connectors**
2. Click **Add custom connector**
3. Fill in:
- **Name**: Pantrist
- **URL**: https://mcp.pantrist.app/mcp
4. Save → click **Connect**. A popup opens the Pantrist consent page.
5. Sign in → authorize → the popup closes.
6. Start a new chat — the Pantrist tools (shopping list, pantry, week plan,
recipes) show up in the tool selector. Try *"What's on my shopping list?"*
Claude Code (CLI)
In the session, run /mcp to confirm it's listed. The first tool call triggers
the OAuth flow in your browser.
Claude Desktop (manual config)
For Claude Desktop versions that support remote MCP, in
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
the equivalent on Windows/Linux:
Restart Claude Desktop. First tool use kicks off OAuth.
Sanity-checks if it doesn't work
If all three succeed but the connector flow still fails, the API's
OAUTH_AUTHORIZE_URL probably isn't set to a browser-facing consent page —
see the warning in the OAuth dependency note.
Quick start (stdio — fastest path)
You can validate the whole tool set in a couple of minutes without touching
OAuth, using an API key you generate in the Pantrist web app.
Claude Desktop config
claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
Restart Claude Desktop, then try: *"What's on my shopping list?"* or
*"Add milk and eggs."*