模型上下文协议（MCP）服务器包裹了Pancake POS REST API，使像Claude这样的AI助手能够利用24个专业工具和7个参考资源管理越南电子商务POS操作。

概述

Pancake POS MCP 将 Pancake POS API（[https://pos.pages.fm/api/v1)）作为模型上下文协议工具，使 Claude 及其他 AI 助手能够在以下领域自动化 POS 管理：

• 核心POS： 订单、产品、客户、库存
• 供应链： 仓库、供应商、采购、转运、盘点
• 销售： 退货、换货、组合、促销、代金券
• CRM： 联系人、优惠、活动
• 多渠道： 电子商务（Shopee/Lazada/TikTok），直播商务
• 运营： 员工、Webhooks、分析、商店信息、地址查询

先修条件

• Bun（运行时）——从 https://bun.sh （curl -fsSL https://bun.sh/install | bash] 安装）
• Pancake POS API 密钥 + 商店 ID — 详见下方获取 Pancake POS 凭证。注意：这是 Pancake POS（电子商务/库存）API，而非 Pancake 用户/社交收件箱 API——不同产品，不同密钥。
• Node.js 18+（可选，用于开发工具）

快速启动

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