Pancake Pos Mcp

Pancake POS MCP

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 (https://pos.pages.fm/api/v1) as Model Context Protocol tools, allowing Claude and other AI assistants to automate POS management across:

• Core POS: Orders, Products, Customers, Inventory
• Supply Chain: Warehouses, Suppliers, Purchases, Transfers, Stocktaking
• Sales: Returns, Exchanges, Combos, Promotions, Vouchers
• CRM: Contacts, Deals, Activities
• Multi-Channel: eCommerce (Shopee/Lazada/TikTok), Livestream Commerce
• Operations: Employees, Webhooks, Analytics, Shop Info, Address Lookup

Prerequisites

• 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](#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](#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:

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

1. 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:

{
  "mcpServers": {
    "pancake-pos": {
      "command": "bun",
      "args": ["run", "/path/to/pancake-pos-mcp/src/index.ts"]
    }
  }
}

HTTP Transport (Remote Access)

Enable Streamable HTTP transport:

bun run src/index.ts --http

Server starts at http://localhost:3000/mcp. Health check: http://localhost:3000/health

With authentication (recommended for production):

# .env
PORT=3000
MCP_AUTH_TOKEN=your_secret_token

# Client usage
curl -H "Authorization: Bearer your_secret_token" http://localhost:3000/mcp

Cloudflare Workers (Serverless Edge)

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

Workers URL: https://pancake-pos-mcp..workers.dev/mcp

Connect Claude Desktop via mcp-remote:

{
  "mcpServers": {
    "pancake-pos": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://pancake-pos-mcp..workers.dev/mcp",
        "--header", "Authorization: Bearer "
      ]
    }
  }
}

Workers characteristics: 8s timeout per upstream call, 2 retries, rate limiter disabled (stateless per-request model). Free tier: 100k requests/day. See [deployment guide](./docs/deployment-guide.md) for full details.

Available Tools

24 tools, grouped by business domain.

Core POS

| Tool | Description | |------|-------------| | manage_orders | Create, read, update, delete, print, ship, manage status; batch_update patches up to 50 orders/call | | manage_products | Product catalog with variations and pricing | | manage_customers | Customer CRUD, reward points, transaction history | | manage_inventory | Inventory reports filtered by warehouse, category, supplier |

Supply Chain & Warehousing

| Tool | Description | |------|-------------| | manage_warehouses | Warehouse CRUD and configuration | | manage_suppliers | Supplier contact and profile management | | manage_purchases | Purchase orders and inbound inventory | | manage_transfers | Warehouse-to-warehouse transfer management | | manage_stocktaking | Physical inventory count records |

Sales Extensions

| Tool | Description | |------|-------------| | manage_returns | Order returns and exchange processing | | manage_combos | Product bundle deals and time-limited offers | | manage_promotions | Discount campaigns (percent/amount-based) | | manage_vouchers | Voucher code generation and usage tracking |

CRM & Multi-Channel

| Tool | Description | |------|-------------| | manage_crm_contacts | CRM contact CRUD and relationship management | | manage_crm_deals | Sales pipeline opportunities and stages | | manage_crm_activities | Calls, meetings, tasks, notes tied to contacts/deals | | manage_ecommerce | Multi-channel sync (Shopee, Lazada, TikTok) | | manage_livestream | Live selling session management and scheduling |

Operations & Business Intelligence

| Tool | Description | |------|-------------| | manage_employees | Staff management and warehouse assignments | | manage_webhooks | Event subscription and webhook configuration | | get_statistics | Inventory, sales, orders with grouping | | analytics | Top orders + revenue summary via server-side ES aggregations (no pagination loops) | | get_shop_info | Shop profile information and settings | | lookup_address | Vietnamese address hierarchy via /geo/* (OLD 3-tier + NEW 2-tier post-2025-07-01) |

Available Resources

Static reference resources (no authentication required):

| Resource | Contents | |----------|----------| | order-statuses | 16 order status codes with Vietnamese/English names | | order-sources | Sales channel codes (Facebook, Shopee, Lazada, etc.) | | sort-options | 22 sort options for order listing | | webhook-events | Webhook event types (order.created, order.updated, etc.) | | error-codes | HTTP error code reference | | rate-limits | API rate limits (1000/min, 10000/hour) | | shipping-partners | Live shipping partner data (cached from API) |

Architecture

• API Client: Token-bucket rate limiting (1000/min, 10000/hour), exponential backoff retries (3 attempts; Workers: 2)
• Tools: 24 MCP tools organized by business domain
• Schema Validation: Zod with discriminated unions, z.coerce.number() for stringified numbers from LLM clients
• Transport: Stdio (default) + Streamable HTTP + Cloudflare Workers with optional Bearer token auth
• 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_orders batch_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

Development

Type Checking

bun run typecheck

Run Tests

bun run test       # vitest (includes Workers tests)

Project Structure

src/
├── api-client/              # HTTP layer with rate limiting
│   ├── pancake-http-client.ts
│   ├── request-builder.ts
│   └── response-parser.ts
├── tools/                   # 24 MCP tools (24 files)
├── resources/               # MCP reference resources
├── shared/                  # Schemas, errors, pagination
├── config.ts                # Environment configuration
├── server.ts                # MCP server factory
├── worker.ts                # Cloudflare Workers entry point
└── index.ts                 # Entry point (stdio + HTTP)

See [docs/code-standards.md](./docs/code-standards.md) for full development guidelines.

Documentation

• [codebase-summary.md](./docs/codebase-summary.md) — Architecture and implementation overview
• [system-architecture.md](./docs/system-architecture.md) — Detailed system design and data flows
• [code-standards.md](./docs/code-standards.md) — TypeScript and tool implementation standards
• [project-overview-pdr.md](./docs/project-overview-pdr.md) — Project requirements and features
• [deployment-guide.md](./docs/deployment-guide.md) — Setup and deployment instructions
• [project-roadmap.md](./docs/project-roadmap.md) — Implementation progress and milestones
• [poscake-api-docs.md](./docs/poscake-api-docs.md) — Complete Pancake POS API reference

Troubleshooting

A few non-obvious gotchas:

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

License

MIT License — See [LICENSE](./LICENSE) file for full text.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nguyennguyenit
• Source: nguyennguyenit/pancake-pos-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.