Purpose
Pantrist MCP Server is a Model Context Protocol (MCP) server that wraps the Pantrist REST API. Its purpose is to enable LLM clients (such as Claude Desktop, the Claude web/mobile connector, Cursor, etc.) to manage shopping lists, pantry items, recipes, and weekly plans in Pantrist through natural language.
Main capabilities
The server is a lightweight wrapper and contains no business logic. Each tool maps to an existing REST endpoint and forwards the caller's Bearer token. The HTTP client is generated from the public OpenAPI specification (src/generated/pantrist-api.ts), so request and response types automatically track changes to the API; only the carefully designed tool layer (src/tools.ts) is handwritten.
It supports the following functional areas: shopping lists, pantry, recipes, and weekly plans. For the parameters of specific tools, REST mappings, and project structure, see docs/TOOLS.md.
Usage
Connecting Claude to the hosted server
If you only need to use Pantrist in Claude (rather than self-hosting), the public endpoint is https://mcp.pantrist.app/mcp . Regardless of which Claude interface you use, the first tool call will guide you through OAuth login to your Pantrist account, with no need to manually copy a token.
Claude.ai (web or desktop app)
- Open claude.ai → profile menu → Settings → Connectors
- Click Add custom connector
- Fill in: Name: Pantrist; URL: https://mcp.pantrist.app/mcp
- Save → click Connect. A Pantrist consent page will pop up.
- Log in → authorize → the popup closes.
- Start a new conversation — the Pantrist tools (shopping lists, pantry, weekly plans, recipes) will appear in the tool selector. Try "What's on my shopping list?"
Claude Code (CLI)
Run /mcp in the session to confirm it is listed. The first tool call will trigger the OAuth flow in the browser.
Claude Desktop (manual configuration)
For versions of Claude Desktop that support remote MCP, configure it in ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the corresponding location on Windows/Linux. Restart Claude Desktop. Using a tool for the first time will start OAuth.
Quick start (stdio — the fastest path)
You can verify the entire toolset in a few minutes without touching OAuth, simply by using an API key generated in the Pantrist web app.
Configure it in 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."
Remote (Streamable HTTP + OAuth)
Then add it as a custom connector to Claude, with the URL https://mcp.pantrist.app/mcp . The server also exposes GET /healthz for probes. For the full environment variable reference, entry points, and extension instructions, see docs/DEPLOYMENT.md.
OAuth handshake flow
The MCP server is the resource server; the authorization server is the Pantrist API. The token Claude receives is an API Bearer, so this server simply 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 protected JSON endpoint and cannot be navigated to directly). One needs to be hosted on the app (for example https://pantrist.app/oauth/authorize），并将 The API's OAUTH_AUTHORIZE_URL environment variable is set to point to it. Until that page exists, use the stdio path above with a manually provided token.
Most tools accept an optional listId; if omitted, they use PANTRIST_LIST_ID only in stdio mode (HTTP mode requires it explicitly — see multi-user isolation). Full parameter and project structure details are in docs/TOOLS.md.
All these endpoints are public API endpoints (present in /swagger-ui-json), so this wrapper only needs the published specification — never the private API source code. This preserves the possibility of open-sourcing this directory as a standalone repository.
Regenerating the API client
When the API contract changes, run two steps. Both the specification 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 handwritten and is not regenerated.
See .env.example.
