Model Context Protocol (MCP) server wrapping the Pancake POS REST API, enabling AI assistants like Claude to manage Vietnamese e-commerce POS operations with 24 specialized tools and 7 reference resources.
Overview
Pancake POS MCP exposes the Pancake POS API () as Model Context Protocol tools, allowing Claude and other AI assistants to automate POS management across:
MCP server for Pancake POS — 23 tools across orders, inventory, CRM, multi-channel commerce. Bun + TypeScript, runs on stdio / HTTP / Cloudflare Workers.
Bun (runtime) — install from https://bun.sh (curl -fsSL https://bun.sh/install | bash)
Pancake POS API Key + Shop ID — see Getting Pancake POS credentials below. Note: this is the Pancake POS (e-commerce / inventory) API, not the Pancake user/social-inbox API — different products, different keys.
Node.js 18+ (optional, for development tooling)
Quick Start
Get from zero to a working MCP server in ~5 minutes:
# 1. Clone the repo
git clone https://github.com/nguyennguyenit/pancake-pos-mcp.git
cd pancake-pos-mcp
# 2. Install dependencies
bun install
# 3. Configure credentials
cp .env.example .env
# Open .env and fill in PANCAKE_POS_API_KEY + PANCAKE_POS_SHOP_ID
# (See "Getting Pancake POS credentials" section below)
# 4. Verify it runs
bun run src/index.ts
# Expected output:
# [pancake-pos-mcp] Server started on stdio transport
# Press Ctrl+C to stop.
# 5. Connect Claude Desktop — see "Stdio Transport" section below
If step 4 prints an error, double-check your .env values and that you ran bun install. Common issues are listed in Troubleshooting.
Getting Pancake POS credentials
⚠️ Pancake POS ≠ Pancake (social inbox). This MCP only works with the Pancake POS product at https://pos.pages.fm — the e-commerce / inventory / order-management system. The Pancake user/inbox API at pages.fm is a different product with a different API key and is not supported here.
You need two values from your Pancake POS account:
PANCAKE_POS_SHOP_ID — the numeric ID of your shop
Log in to https://pos.pages.fm and check the URL or shop settings to find the numeric shop ID
PANCAKE_POS_API_KEY — your Pancake POS API token
Pancake POS Dashboard → Cài đặt (Settings) → API → Generate API key
Copy the key immediately — it is only shown once
Keep both values secret. Never commit them to git. The .gitignore already excludes .env and .dev.vars.
Configuration
Required (set in Quick Start):
Variable
Purpose
PANCAKE_POS_API_KEY
Pancake POS API token
PANCAKE_POS_SHOP_ID
Numeric shop ID
Optional:
Variable
Default
Purpose
PANCAKE_POS_BASE_URL
https://pos.pages.fm/api/v1
Override API endpoint
PORT
3000
HTTP transport port
MCP_AUTH_TOKEN
(none)
Bearer token for HTTP/Workers auth
Usage
Stdio Transport (Claude Desktop)
Default mode. Add to Claude Desktop config claude_desktop_config.json:
Deploy globally on Cloudflare Workers for low-latency access from anywhere:
# Local development (uses .dev.vars for secrets)
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your credentials
bun run dev:workers
# Runs at http://localhost:8787
# Deploy to Cloudflare
wrangler login
bun run deploy
# Set production secrets
wrangler secret put PANCAKE_POS_API_KEY
wrangler secret put PANCAKE_POS_SHOP_ID
wrangler secret put MCP_AUTH_TOKEN
Error Handling: Structured error responses with code and message
Compact responses:verbosity: "compact" (default) trims payloads 60–85% on orders, products, warehouses, lookup_address; "full" for debugging
Bulk ops:manage_ordersbatch_update action patches up to 50 orders per call
Display ID resolver:manage_orders action=delete defaults to interpreting order_id as display_id (small per-shop number like 521 or 'A483') via a two-stage search+scan resolver; set id_kind="id" to pass internal Pancake id directly. Returns structured error codes: LIKELY_INTERNAL_ID, NOT_FOUND_DISPLAY_ID, AMBIGUOUS_DISPLAY_ID, NOT_DRAFT, STATUS_UNKNOWN, ORDER_NOT_FOUND, ORDER_GONE.
Replay validation:tests/replay/ re-runs production traces against local handlers to gate response-size regressions
429 Too Many Requests — hit Pancake rate limit (1000/min, 10000/hour). The built-in token bucket auto-throttles; reduce parallelism on the caller side.
Tests fail with Cannot find package 'cloudflare:test' — use bun run test (vitest), not native bun test. Workers tests need the vitest pool worker plugin.
Claude Desktop doesn't see the tools — the command/args path in claude_desktop_config.json must be absolute. Restart Claude Desktop after editing the config.
For other errors, check the error message and verify .env credentials.
MCP server for Pancake POS — 23 tools across orders, inventory, CRM, multi-channel commerce. Bun + TypeScript, runs on stdio / HTTP / Cloudflare Workers.