sapo-mcp
Model Context Protocol server for Sapo.vn POS & e-commerce platform.
接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令? 两种安装方式的区别
来自发布者
Model Context Protocol server for Sapo.vn POS & e-commerce platform.
Model Context Protocol server for Sapo.vn POS & e-commerce — 105 tools across 4 modes, stdio + Streamable HTTP, single-tenant Private App.
pos-online (51), web (31), pos-counter (15), analytics (10) — 2 read tools shared between pos-online and webSAPO_ALLOW_OPS (default: none); all destructive calls also require confirm: trueRequires Node.js 20 or newer. Verify with node --version.
Recommended for MCP clients (Claude Desktop, Cursor). Always pulls the latest published version:
npx -y sapo-mcp@latest --version
npm install -g sapo-mcp
sapo-mcp --version
sapo-mcp --help
npm install sapo-mcp
npx sapo-mcp --mode=pos-online
Create a Private App at developers.sapo.vn:
mystorename → mystorename.mysapo.netEdit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):
{
"mcpServers": {
"sapo": {
"command": "npx",
"args": ["-y", "sapo-mcp", "--mode=pos-online,web,analytics"],
"env": {
"SAPO_STORE": "mystorename",
"SAPO_API_KEY": "xxx",
"SAPO_API_SECRET": "yyy"
}
}
}
}
Restart Claude Desktop. Tools appear under the 🔌 plug icon.
Edit ~/.cursor/mcp.json or per-workspace .cursor/mcp.json:
{
"mcpServers": {
"sapo": {
"command": "npx",
"args": ["-y", "sapo-mcp", "--mode=pos-online,web"],
"env": {
"SAPO_STORE": "mystorename",
"SAPO_API_KEY": "xxx",
"SAPO_API_SECRET": "yyy"
}
}
}
}
npx @modelcontextprotocol/inspector \
-e SAPO_STORE=mystorename \
-e SAPO_API_KEY=xxx \
-e SAPO_API_SECRET=yyy \
npx -y sapo-mcp --mode=pos-online
Open the printed URL in a browser to inspect/invoke registered tools.
Use --mode=pos-online,web,analytics to register multiple modes (union of tools; shared tools registered once).
*One of SAPO_API_SECRET or SAPO_API_SECRET_FILE is required.
†HTTP-only. Token is enforced when SAPO_HTTP_HOST is not 127.0.0.1/localhost/::1.
Note:
pos-counterexcludes 5 internal-only endpoints (purchase_orders,purchase_returns,stock_adjustments,cash_transactions,cashbook) — these return HTTP 403 for Private App credentials and require an OAuth Partner App (post-1.0 roadmap).Analytics tools auto-paginate up to
SAPO_MAX_AUTO_PAGES; results carrytruncated: truewhen the cap is hit.
Verification levels for the 105 unique tools (last updated 2026-04-30):
These 2 tools may fail at runtime. POS shift management currently requires admin UI.
Click each section to expand the full tool list with status icons.
Customers (7)
list_customers, get_customer, search_customers, count_customers, list_customer_orderscreate_customer, update_customerCustomer Addresses (4)
list_customer_addresses, add_customer_address, update_customer_address, set_default_customer_addressProducts (read) (4)
list_products, get_product, search_products, count_productsVariants (read) (2)
list_variants_for_product, get_variantInventory (read) (1)
get_inventory_levelsOrders (4)
list_orders, get_order, count_orders, search_ordersOrder Transactions (2)
list_order_transactions, create_order_transactionFulfillments (4)
list_fulfillments_for_order, get_fulfillmentcreate_fulfillment, update_fulfillment_trackingRefunds (3)
list_refunds, get_refund, create_refund (create_refund destructive: SAPO_ALLOW_OPS=refund)Draft Orders (7)
list_draft_orders, get_draft_ordercreate_draft_order, update_draft_order, complete_draft_order, send_draft_order_invoice, delete_draft_order (destructive: delete)Price Rules (5)
list_price_rules, get_price_rulecreate_price_rule, update_price_rule, delete_price_rule (destructive: delete)Discount Codes (3)
list_discount_codes, create_discount_code, delete_discount_code (destructive: delete)Destructive (cancel/delete-strict) (4)
cancel_order, close_order, cancel_fulfillment (destructive: cancel)delete_customer, delete_variant (destructive: delete_strict)Store (1)
get_store_infoArticles (5)
list_articles, get_article, create_article, update_article, delete_article (destructive: delete)Blogs (5)
list_blogs, get_blog, create_blog, update_blog, delete_blog (destructive: delete)Pages (4)
list_pages, get_pageupdate_page_seo, delete_page (destructive: delete)Collections (10)
list_custom_collections, get_custom_collection, create_custom_collection, update_custom_collection, delete_custom_collection (destructive: delete)list_smart_collections, get_smart_collectionlist_collects, create_collect, delete_collect (destructive: delete)Script Tags (3)
list_script_tags, create_script_tag, delete_script_tag (destructive: delete)Products SEO (1)
update_product_seoVariants (read, shared) (2)
list_variants_for_product, get_variantLocations (2)
list_locations, get_locationPayment Methods (1)
list_payment_methodsInventory (write) (3)
adjust_inventory_level, connect_inventory_levelset_inventory_level (destructive: inventory_set)Variants (write) (1)
update_variantPOS Orders (2)
list_pos_orders, get_pos_order (uses /admin/orders?source_name=pos)Suppliers (2)
list_suppliers, get_supplierStock Transfers (2)
list_stock_transfers, get_stock_transferPOS Shifts (2)
list_pos_shifts, get_pos_shift (see Broken section above — endpoint returns HTML)All 10 are 🔵 composed (aggregate from multiple Sapo endpoints, no single endpoint to verify):
revenue_summary, top_products, top_customers, customer_ltv, tax_summary, online_vs_counter_breakdown, discount_usage_report, shift_report, inventory_low_stock, inventory_value
Destructive tools (cancel, delete, bulk-delete) are blocked by default. To enable specific categories:
# Allow order cancellation and standard deletes only
SAPO_ALLOW_OPS=cancel,delete npx sapo-mcp --mode=pos-online
Supported categories: cancel, delete, delete_strict, inventory_set, refund, shift_close, cashbook_write.
All destructive tool calls also require confirm: true in the tool arguments — this prevents accidental execution when an LLM calls the tool without explicit intent.
ENV credentials are visible to other processes via ps / /proc/<pid>/environ on shared hosts. Use SAPO_API_SECRET_FILE to pass the secret via a file instead of an env var where possible.
Note: full secret-file isolation (reading the secret only at startup, then clearing) is tracked for the post-1.0 roadmap.
Verify which Sapo API endpoints are available on your store before configuring tools.
# Read-only probe — safe to run against any store (GET only)
SAPO_STORE=mystore SAPO_API_KEY=xxx SAPO_API_SECRET=yyy npm run probe
# Schema drift check — same probe + Zod validation against fixtures
npm run canary
Write-probe (npm run probe:write) refuses to run unless SAPO_STORE contains test, dev, or sandbox — never against production.
Run as an HTTP server for remote MCP clients (e.g. GoClaw) or self-hosted Docker:
# Local-only (no auth required)
sapo-mcp --mode=pos-online --transport=http --port=3333
# Public bind (auth token required)
SAPO_HTTP_HOST=0.0.0.0 \
SAPO_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
sapo-mcp --mode=pos-online --transport=http
Endpoints:
Session model: Each MCP client gets a UUID session, isolated by an
McpServer instance. Idle sessions (SAPO_HTTP_SESSION_IDLE_MS) are
evicted automatically. Concurrent sessions cap at SAPO_HTTP_MAX_SESSIONS
(503 returned when full).
Security:
127.0.0.1 — loopback only. Token optional.SAPO_HTTP_HOST=0.0.0.0 (or any non-loopback) requires
SAPO_MCP_AUTH_TOKEN. The server refuses to start otherwise.SAPO_HTTP_CORS_ORIGINS
(CSV of origins, or * for all). Only enable when serving browser-based
agents.docker build -f examples/Dockerfile -t sapo-mcp:local .
docker run --rm -p 3333:3333 \
-e SAPO_STORE=mystore \
-e SAPO_API_KEY=xxx -e SAPO_API_SECRET=yyy \
-e SAPO_HTTP_HOST=0.0.0.0 \
-e SAPO_MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
sapo-mcp:local
npm install
npm run typecheck # Type check
npm run lint # Lint
npm run test # Run tests
npm run build # Build for release
The 1.0.0 stable cut is gated on the following items, deferred from this release:
sapo://shop/info, sapo://orders/today, sapo://orders/pending, sapo://inventory/low-stock. Read-heavy data is more efficient as a Resource than repeated tool calls.respond_to_complaint, weekly_report, seo_optimize_product, customer_followup).pos-counter and 4 deferred finance/PO reports (cashflow_summary, pnl_summary, supplier_purchase_summary, daily_pos_report).See CHANGELOG.md for the per-version history.
MIT — See LICENSE
Model Context Protocol server for Sapo.vn POS & e-commerce — 105 tools across 4 modes, stdio + Streamable HTTP, single-tenant Private App.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Sapo 通过 stdio 在本地运行。
上次检查时间:2026-10-27。 Model Context Protocol server for Sapo.vn POS & e-commerce — 105 tools across 4 modes, stdio + Streamable HTTP, single-tenant Private App.