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 23 specialized tools and 7 reference resources.
Ask AI about Pancake Pos MCP
Powered by Claude Β· Grounded in docs
I know everything about Pancake Pos MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 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.fmis 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
.gitignorealready excludes.envand.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.<your-subdomain>.workers.dev/mcp
Connect Claude Desktop via mcp-remote:
{
"mcpServers": {
"pancake-pos": {
"command": "npx",
"args": [
"mcp-remote",
"https://pancake-pos-mcp.<your-subdomain>.workers.dev/mcp",
"--header", "Authorization: Bearer <your-token>"
]
}
}
}
Workers characteristics: 8s timeout per upstream call, 2 retries, rate limiter disabled (stateless per-request model). Free tier: 100k requests/day. See deployment guide 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_ordersbatch_updateaction patches up to 50 orders per call - 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 for full development guidelines.
Documentation
- codebase-summary.md β Architecture and implementation overview
- system-architecture.md β Detailed system design and data flows
- code-standards.md β TypeScript and tool implementation standards
- project-overview-pdr.md β Project requirements and features
- deployment-guide.md β Setup and deployment instructions
- project-roadmap.md β Implementation progress and milestones
- 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'β usebun run test(vitest), not nativebun test. Workers tests need the vitest pool worker plugin. - Claude Desktop doesn't see the tools β the
command/argspath inclaude_desktop_config.jsonmust 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 file for full text.
