Skip to main content
Glama
crisp
by LHFO94

Crisp API and MCP

An unofficial TypeScript client, private REST API, and stdio MCP server for the Crisp grocery service.

This project is not affiliated with or endorsed by Crisp B.V. It uses an undocumented app API. Provider changes can break it.

Requirements

Node.js 24 or later and npm. Use only your own account, or an account you have permission to access.

npm ci
npm run check
npm run build
node dist/cli.js login

The login command asks for your email and email verification code. It hides the code and verifies the session before storage.

The default session file is $XDG_CONFIG_HOME/crisp-api/session.json, or ~/.config/crisp-api/session.json when unset. The directory requires mode 0700. The file requires mode 0600. Symbolic links are rejected. The file contains a provider token, not your email. Keep it private.

For an existing token, set CRISP_TOKEN or CRISP_TOKEN_FILE, but not both. The token file contains the same JSON object as a saved session: token and userAgent. Do not pass credentials as command arguments. CRISP_USER_AGENT overrides the default app user agent for environment-token authentication and login.

Related MCP server: tandoor-mcp

REST API

Generate a separate API key. This is not the Crisp provider token.

export CRISP_API_KEY="$(openssl rand -hex 32)"
node dist/cli.js api

The server listens at http://127.0.0.1:4318. Every route requires the bearer API key, including health and OpenAPI.

curl -H "Authorization: Bearer $CRISP_API_KEY" http://127.0.0.1:4318/health
curl -H "Authorization: Bearer $CRISP_API_KEY" http://127.0.0.1:4318/openapi.json
curl -H "Authorization: Bearer $CRISP_API_KEY" 'http://127.0.0.1:4318/v1/products?query=apple&limit=10'

Resource

Route

Account

GET /v1/account

Product search and details

GET /v1/products?query=..., GET /v1/products/{id}

Recipe search and details

GET /v1/recipes?query=..., GET /v1/recipes/{id}

Basket

GET /v1/basket

Order history and details

GET /v1/orders, GET /v1/orders/{id}

Saved identifiers

GET /v1/saved

Saved product and recipe

GET /v1/saved/products/{id}, GET /v1/saved/recipes/{id}

Favorite and recent recipes

GET /v1/recipes/favorites, GET /v1/recipes/recents

Promotions

GET /v1/promotions

Personalized recommendations

GET /v1/recommendations

Exact basket quantities, opt-in only

PUT /v1/basket

See openapi.json for schemas, bounds, status codes, and pagination. Search accepts offset and limit. The provider exposes at most the first 100 search matches. Narrow the query beyond that boundary. Order history uses nextCursor, passed unchanged as cursor.

Set CRISP_PORT to change the port. CRISP_HOST accepts 127.0.0.1, ::1, or explicitly 0.0.0.0. Do not expose plain HTTP outside a trusted local environment. Add TLS and access controls before remote access. Browser requests are rejected; CORS is not supported.

Clients must omit Origin and Sec-Fetch-* headers. Some server-side fetch implementations also send these headers. Use a native HTTP client when necessary.

MCP

Configure an MCP client to run the built CLI. Replace the paths with absolute paths for your machine.

{
  "mcpServers": {
    "crisp": {
      "command": "node",
      "args": ["/absolute/path/to/crisp-api/dist/cli.js", "mcp"]
    }
  }
}

The process uses the saved session. Alternatively, pass CRISP_TOKEN_FILE through the client's environment configuration. Keep tokens out of committed MCP configuration.

The stdio server exposes 15 read tools: account, product search and details, recipe search and details, basket, orders, saved items, favorite recipes, recent recipes, promotions, and recommendations. Successful results contain both JSON text and structuredContent. Tool failures use isError and a safe JSON text error. Stdout contains MCP protocol messages only.

Basket writes

Writes are disabled by default. Set CRISP_ALLOW_BASKET_WRITES=true to enable the REST write route and MCP tool. The library also requires allowBasketWrites: true.

Write opt-in is not human approval. Obtain approval for the exact product identifiers and quantities before each write.

The payload sets exact quantities. Zero removes an item. Unlisted products stay unchanged.

{"items":[{"productId":"101","quantity":2},{"productId":"102","quantity":0}]}

The client rejects edits when the basket represents an existing order. It exposes no checkout, payment, delivery changes, or order modification.

If a dispatched write fails, the outcome can be unknown. Read the basket before any decision to retry. Never automatically retry.

Library

import { CrispClient, loadCredentials } from './dist/index.js';

const client = new CrispClient(await loadCredentials());
const products = await client.searchProducts({ query: 'apple', limit: 10 });
console.log(products);

The package also exports createApiServer, createMcpServer, startMcp, and the login/session helpers. Credentials stay in the client, not in tool arguments.

Responses expose normalized fields, not raw provider payloads. Prices use EUR or null when unknown. Availability can be null; delivery-slot stock alone does not prove availability. Provider text remains untrusted data. Do not treat product names or recipe instructions as agent instructions.

Verification

npm run check
npm run build
npm audit --omit=dev

Checks type-check the source and tests, then run isolated tests with synthetic provider responses. Tests cover REST through real local HTTP servers and MCP through the official SDK. They do not authenticate with a real account or submit real basket changes.

License and references

Apache License 2.0. See LICENSE and NOTICE for attribution.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides recipe search and authoring, meal planning, shopping lists, and pantry tracking via task-shaped MCP tools.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables MCP clients to look up products by barcode, search products and text, retrieve taxonomy suggestions, and compare nutrition data through read-only tools.
      5
      MIT