Skip to main content
Glama
Pantrist

Pantrist

Official
by Pantrist-dev

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 (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)

claude mcp add pantrist --transport http https://mcp.pantrist.app/mcp

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:

{
  "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-resource

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.

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

Claude 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.js

Then 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 API

The 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_endpoint must be a browser-navigable login/consent page (the API's /access-token/authorize is 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's OAUTH_AUTHORIZE_URL env to point at it. Until that page exists, use the stdio path above with a manually-supplied token.

Tools

Tool

REST route

list_lists

GET /list

whoami

GET /user-management/me

list_supermarkets

GET /list/{listId}/supermarkets

list_shopping_items

GET /list/{listId}/shoppingList

add_shopping_item

POST /list/{listId}/shoppingList/add-by-name

check_shopping_item

POST /list/{listId}/shoppingList/{itemId}/check

delete_shopping_item

DELETE /list/{listId}/shoppingList/{itemId}

list_pantry_items

GET /list/{listId}/pantryList

add_pantry_item

POST /list/{listId}/pantryList/add-by-name

reduce_pantry_amount

PUT /list/{listId}/pantryList/{itemId}/change-amount

update_pantry_item

GET + PUT /list/{listId}/pantryList/{itemId} (metadata-only; stock changes go through reduce_pantry_amount)

reserve_pantry_for_recipe

PUT /list/{listId}/pantryList/{itemId}/reservations/{recipeUuid} (+ GET /list/{listId}/pantryList with recipeName)

list_recipe_reservations

GET /list/{listId}/pantryList

cook_recipe

POST /list/{listId}/pantryList/reservations/{recipeUuid}/cooked

release_recipe_reservation

DELETE /list/{listId}/pantryList/{itemId}/reservations/{recipeUuid} or DELETE /list/{listId}/pantryList/reservations/{recipeUuid}

search_recipes

POST /recipe/filter

get_recipe

GET /recipe/{recipeId}

delete_recipe

DELETE /recipe/{recipeId}

create_recipe

POST /recipe (+ PUT /recipe-collection/recipe/{recipeId} with collectionIds)

update_recipe

GET /recipe/{recipeId} + PUT /recipe

list_recipe_collections

GET /recipe-collection

create_recipe_collection

POST /recipe-collection

add_recipe_to_collection

GET /recipe-collection/with-connected-recipe/{recipeId} + PUT /recipe-collection/recipe/{recipeId}

remove_recipe_from_collection

same as add_recipe_to_collection

get_week_plan

GET /list/{listId}/weekPlan?from=&to=

update_week_plan_day

PUT /list/{listId}/weekPlan/{date}

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 gating

Regenerating 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:client

Both 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 tools
add_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

    A4.5/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessMixed handling

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      10
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Household-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