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.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
2. 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):

Optional:

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 (Server

... View full README on GitHub