Pantrist
OfficialManage Pantrist shopping lists, pantry stock, recipes, and weekly meal plans through a thin MCP wrapper over the Pantrist REST API.
Shopping lists: discover lists, list shopping items, add items by name, check items off (with list-dependent mark-done/remove/move-to-pantry behavior), and hard-delete items.
Pantry: list stocked items, add pantry items with optional amount/unit, adjust stock by delta (with optional auto-restock onto the shopping list), and update item metadata like name, brand, notes, unit, or category.
Recipes: search recipes with pagination and category filters, fetch full recipe details, and delete recipes you own.
Week plan: read meal-plan entries for a date range and replace all entries for a single day with recipe references or manual free-text meals.
Pantrist MCP Server
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).
Related MCP server: Bring! Shopping MCP Server
Two transports
Transport | When | Auth |
stdio ( | Local PoC, single user, Claude Desktop | Bearer from |
Streamable HTTP ( | 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)
claude.ai → profile menu → Settings → Connectors
Click Add custom connector
Fill in:
Name:
PantristURL:
https://mcp.pantrist.app/mcp
Save → click Connect. A popup opens the Pantrist consent page.
Sign in → authorize → the popup closes.
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)
claude mcp add pantrist --transport http https://mcp.pantrist.app/mcpIn 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:
{
"mcpServers": {
"pantrist": {
"type": "url",
"url": "https://mcp.pantrist.app/mcp"
}
}
}Restart Claude Desktop. First tool use kicks off OAuth.
Sanity-checks if it doesn't work
# 200 OK + {"status":"ok"}
curl -fsS https://mcp.pantrist.app/healthz
# 401 + a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource
curl -i -X POST https://mcp.pantrist.app/mcp -H 'Content-Type: application/json' -d '{}'
# JSON listing api.pantrist.app as the authorization server
curl -fsS https://mcp.pantrist.app/.well-known/oauth-protected-resourceIf 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.
git clone https://github.com/NLueg/pantrist-mcp.git
cd pantrist-mcp
npm install
npm run build
# Generate an API key at
# https://www.pantrist.com/documentation/api-docs — it never expires,
# which is what you want for a server that stays running.
export PANTRIST_BASE_URL=https://api.pantrist.app
export PANTRIST_TOKEN=<uuid>_<secret>
export PANTRIST_LIST_ID=<a-list-uuid> # optional; or call list_lists
npm run dev:stdio # or: node dist/stdio.jsClaude Desktop config
claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"pantrist": {
"command": "node",
"args": ["/ABSOLUTE/PATH/pantrist-mcp/dist/stdio.js"],
"env": {
"PANTRIST_BASE_URL": "https://api.pantrist.app",
"PANTRIST_TOKEN": "<uuid>_<secret>",
"PANTRIST_LIST_ID": "<list-uuid>"
}
}
}
}Restart Claude Desktop, then try: "What's on my shopping list?" or "Add milk and eggs."
Remote (Streamable HTTP + OAuth)
export PANTRIST_BASE_URL=https://api.pantrist.app
export MCP_PUBLIC_URL=https://mcp.pantrist.app # public URL of THIS server
export MCP_ALLOWED_HOSTS=mcp.pantrist.app # optional DNS-rebinding guard
export PORT=8787
npm run dev:http # or: node dist/http.jsThen add it in Claude as a Custom Connector with URL
https://mcp.pantrist.app/mcp. The server also exposes GET /healthz for
probes. Full env reference, ingress, and scaling notes are in
docs/DEPLOYMENT.md.
How the OAuth handshake flows
Claude ──POST /mcp (no token)──▶ MCP server
◀── 401 + WWW-Authenticate: resource_metadata=".../oauth-protected-resource"
Claude ──GET /.well-known/oauth-protected-resource ──▶ MCP server
◀── { authorization_servers: ["https://api.pantrist.app"] }
Claude ──GET /.well-known/oauth-authorization-server ─▶ pantrist-api (RFC 8414)
Claude ──POST /access-token/register ─────────────────▶ pantrist-api (RFC 7591 DCR)
Claude ──(browser) authorization_endpoint ────────────▶ consent page (see below)
Claude ──POST /access-token/token (code + PKCE) ──────▶ pantrist-api → access_token
Claude ──POST /mcp (Bearer access_token) ─────────────▶ MCP server ──▶ REST APIThe MCP server is the Resource Server; the Authorization Server is the Pantrist API. The token Claude receives is the API Bearer, so this server just forwards it.
⚠️ Dependency — the consent page. The API's
authorization_endpointmust be a browser-navigable login/consent page (the API's/access-token/authorizeis a guarded JSON endpoint and can't be navigated to directly). Host one on the app (e.g.https://pantrist.app/oauth/authorize) and set the API'sOAUTH_AUTHORIZE_URLenv to point at it. Until that page exists, use the stdio path above with a manually-supplied token.
Tools
Tool | REST route |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| same as |
|
|
|
|
Most tools accept an optional listId; if omitted they use PANTRIST_LIST_ID
in stdio mode only (HTTP mode requires it explicitly — see
multi-user isolation). Full
argument and item-shape details are in docs/TOOLS.md.
All of these are public API endpoints (present in /swagger-ui-json), so
this wrapper needs only the published spec — never the private API source. That
keeps the door open to open-sourcing this directory as its own repo.
Tests
npm test # Node's built-in test runner (via tsx) — wiring + multi-user gatingRegenerating the API client
Two steps, run when the API contract changes:
# 1. In the pantrist-api repo: emit the public OpenAPI spec
# (Nest preview mode — no DB). Writes the snapshot directly into
# ../pantrist-mcp/openapi/pantrist-openapi.json.
cd ../pantrist-api && pnpm generate:openapi
# 2. Back here: regenerate the typed client from that spec.
cd ../pantrist-mcp && npm run generate:clientBoth the spec snapshot (openapi/pantrist-openapi.json) and the generated
client (src/generated/pantrist-api.ts) are committed so the project builds
without network access. The tool layer in src/tools.ts is hand-authored and
not regenerated.
Environment
See .env.example.
Available Tools
14 toolsadd_pantry_itemA
Add a new item to the pantry by name. The API matches name against the user's article catalog: an existing article is reused (its category, unit, price history preserved); a new article is created on first use. Returns the resulting ArticleDto. Use reduce_pantry_amount to change stock on an item already in the pantry; use update_pantry_item to rename or change unit / category; use add_shopping_item to put it on the shopping list instead.
Inputs: name (required), amount, unitId, listId.
add_shopping_itemA
Add an item to the shopping list by name. The API matches name against the user's article catalog: an existing article is reused (its category, unit and price history preserved); a new article is created on first use. Returns the resulting ArticleDto. To add directly to the pantry instead use add_pantry_item; to mark an existing shopping item bought use check_shopping_item.
Inputs: name (required), listId.
check_shopping_itemA
Check off a shopping-list item. The list's settings decide the actual effect: markDone flags the item as bought (stays on the list, struck through), removeOnCheck deletes it, and moveOnCheck transfers it into the pantry. Mutates state and returns the updated row. To unconditionally remove regardless of list settings use delete_shopping_item; for stock changes on a pantry item use reduce_pantry_amount.
Inputs: itemId (required), listId.
delete_recipeA
Delete a recipe you own, unconditionally and irreversibly. The API rejects deletes for recipes belonging to another user with a 403; that error surfaces verbatim to the caller. Preview with get_recipe before calling to confirm authorship and contents.
Inputs: recipeId (required).
delete_shopping_itemA
Remove an item from the shopping list, unconditionally and irreversibly (no soft-delete, not affected by list removeOnCheck setting). Returns a confirmation string; the row is gone after the call returns. Use check_shopping_item instead if you want list-setting-dependent behaviour (mark done / move to pantry) rather than a hard delete.
Inputs: itemId (required), listId.
get_recipeA
Get a single recipe by its uuid. Read-only. Returns a full RecipeDto with name, description, ingredients[], steps[], imageUrls[], totalTime, categories[], etc. Use search_recipes to discover recipe uuids; use delete_recipe to remove one you own.
Inputs: recipeId (required).
get_week_planA
List meal-plan entries between two dates (inclusive). Read-only. Returns an array of day objects — [{ date, list: [{ type: "recipe" | "manual", uuid?, name? }, …] }, …] — one per day that has any entries. Days with no plan are omitted from the response (so an empty array means nothing is planned in the range, not that the range is invalid). To set or clear a single day use update_week_plan_day.
Inputs: from (required), to (required), listId.
list_listsA
List the shopping lists / pantries the authenticated user can access. Read-only. Returns an array of list objects each with uuid, name, and the user's role on that list — use a returned uuid as the listId argument for every other tool here.
Inputs: no named parameters.
list_pantry_itemsA
List all items currently stocked in the pantry for listId. Read-only. Returns an array of ArticleDto objects (uuid, name, amount = current stock, unitId, pantrySettings.earliestBestBefore for expiry tracking, minimumAmount, …); empty array if the pantry is empty. For shopping items use list_shopping_items; for stock changes on an existing item use reduce_pantry_amount; for metadata changes use update_pantry_item.
Inputs: listId.
list_shopping_itemsA
List all items currently on the shopping list for listId. Read-only. Returns an array of ArticleDto objects (uuid, name, amount, unitId, categoryUuid, pantrySettings, …); empty array if the list is empty. For pantry items use list_pantry_items; to add a new shopping item use add_shopping_item.
Inputs: listId.
reduce_pantry_amountA
Change the stock of an existing pantry item by a delta. Mutates state and returns the updated ArticleDto. If autoRestock is true and the new amount lands at or below the item's minimumAmount, the item is also added to the shopping list in the same call. Use add_pantry_item to create a new pantry entry; use update_pantry_item for metadata (name / unit / category) — this tool only touches stock.
Inputs: itemId (required), amountChange (required), autoRestock, listId.
search_recipesA
Search the user's recipes (their own creations + public favourites) by free-text and optional category filters. Read-only and paginated — returns { results: RecipeDto[], totalCount, totalPages, currentPage }. To fetch a single recipe by uuid use get_recipe; to delete one you own use delete_recipe.
Inputs: searchString, categories, currentPage.
update_pantry_itemA
Update an existing pantry item's metadata (rename, change unit, category, brand, notes). Internally fetches the current ArticleDto and PUTs back a merged copy — only the fields you pass change; everything else (current stock, price history, image URLs, autoRestock config) round-trips unchanged. Two API calls per invocation. Returns the updated ArticleDto. Use reduce_pantry_amount for stock changes — this tool only touches metadata.
Inputs: itemId (required), name, brand, categoryUuid, +3 more.
update_week_plan_dayA
Replace the meal-plan entries for one day, identified by date. list is a full replacement — the day's previous entries are discarded. Pass an empty array to clear the day entirely. Returns the new { date, list }. To read a date range use get_week_plan; to read a single recipe referenced in the plan use get_recipe.
Inputs: date (required), list (required), listId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct action and resource (pantry, shopping, recipes, week plan, lists). Overlaps like check_shopping_item vs delete_shopping_item are clearly differentiated by behavior. No ambiguity between tools.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_pantry_item, check_shopping_item, update_week_plan_day). Verbs and targets are uniformly structured.
14 tools cover the main domains (pantry, shopping, recipes, week plan, lists) with a balanced number per domain. No tool feels redundant or missing for the apparent scope.
Core workflows are covered, but gaps exist: no delete pantry item, no create recipe, and only reduce stock (no increase). Week plan and shopping list are well covered. Minor gaps, not severely incomplete.
Maintenance
Related MCP Connectors
Plan weekly meals from your pantry, search allergy-safe recipes, and build grocery lists. Reads and updates your Cooking with Robots pantry, generates a 7-day plan that respects your allergies and preferences, and returns recipes with macros and a grocery gap list. Sign in with OAuth.
AnyList MCP server for ChatGPT, Claude and any AI agent: list shopping lists, add list item, cross off item, read recipe, create recipe, add recipe to meal plan and add meal plan ingredients to list in your own AnyList account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to AnyList yourself; Cotlet does not store your password and you need no AnyList API key. About the official AnyList API: AnyList has no public API, developer docs or official MCP server (checked 25 Oct 2026). The official connections are voice entry with Siri and Amazon Alexa, and an iCalendar link that shows your meal plan in a calendar app. Setup and FAQ: https://cotlet.dev/integrations/anylist-api-mcp-server
Household-aware cooking brain: pantry, meal suggestions, dietary safety, recipes, shopping lists.
Scraps Kitchen gives any AI agent a persistent, household-aware kitchen memory. Unlike generic chatbot recall, Scraps maintains structured cooking data: what's in your fridge (with freshness tracking), who you cook for (with allergens, dietary restrictions, and preferences), your recipe collection (with cook notes and per-diner ratings), your shopping list, and your kitchen equipment. 27 tools across 6 domains let agents read kitchen context, suggest meals that respect dietary safety, update the pantry after cooking, and build a history of what works for your household. Every interaction makes the data richer. Cooking history, preference signals, kitchen awareness = better suggestions next time. All tools work via oAuth and a free scraps.kitchen account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search products, manage shopping carts, place orders, and retrieve order history from Amazon and Target accounts.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables interaction with Bring! shopping lists through natural language, allowing users to manage shopping items, lists, and collaborate with other users via the unofficial Bring! API.153 npm35MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with AnyList for managing shopping lists, recipes, and meal planning. Users can retrieve recipe details, add ingredients to lists, and schedule meals on their AnyList calendar.10ISC
- AlicenseNot gradedqualityDmaintenanceHousehold-aware kitchen brain for AI agents: manage pantry inventory with freshness tracking, shopping lists, recipe collections with cook notes and per-diner ratings, dietary profiles with allergen safety, and kitchen equipment — all through 27 tools with OAuth 2.1 authentication. Includes a free tool for ingredient-based recipe generation without an account (accounts are free!).MIT