FastPospal
FastPospal is a Python SDK and MCP Server for automating interactions with the 银豹 (PosPal) POS web backend, enabling AI agents (e.g., Cursor, Claude Desktop) and programs to manage products, members, inventory, stock flows, and sales records.
Session & Authentication
View current login session details and force re-login
Check if official PosPal OpenAPI appId/appKey are configured
Product Category Management
Retrieve the full category tree; create, rename, and batch delete categories
Product Management
Get product count statistics, paginated product listing, and keyword search
Fetch product details by ID or barcode
Create, update, and delete products
Member (Customer) Management
Look up members by card number or phone; paginated listing with status filtering
Retrieve supplementary member info (punch cards, benefit cards, gift cards, coupons)
Create, update, and soft-delete members
Inventory & Stock Management
Paginated store-wide inventory summary
View stock change history for a specific product over a time range
Set min/max stock thresholds for a product
Logistics / Stock Flows
Paginated stock movement records (purchases, outbound, transfers)
Suppliers
Retrieve the full supplier list
Sales & Orders
Paginated sales tickets (valid, voided, returns, member, wholesale)
Paginated self-operated online shop orders and purchase order records
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FastPospal show me today's product count"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FastPospal
银豹 PosPal Python SDK 与 MCP Server
FastPospal 是一个面向 银豹 PosPal Web 后台 的 Python SDK 与 MCP Server,为开发者和 AI Agent 提供商品、会员、库存、货流、单据等业务能力的统一自动化接口。
声明
本项目为社区维护项目,与银豹官方不存在任何关联。
请仅在拥有合法授权的账号和门店中使用。
本项目旨在提高自动化集成效率,不提供任何绕过认证或破解系统的能力。
如官方开放平台能够满足业务需求,建议优先使用官方接口。
✨ 特性
Python SDK
FastMCP Server(STDIO / HTTP)
商品、分类、会员 CRUD
库存、货流、单据查询
Cursor / Claude Desktop 开箱即用
uv 管理依赖
Docker、systemd、Nginx 部署支持
Related MCP server: MCP Shopline
为什么选择 FastPospal?
银豹官方开放平台覆盖能力有限,而 Web 后台拥有更丰富的业务接口。
FastPospal 对这些能力进行了统一封装:
Python 程序可直接调用
AI Agent 可通过 MCP 自动调用
后续可扩展 CLI、REST API 等能力
MCP 只是接口形式,Python SDK 才是核心能力。
快速开始
安装 uv
brew install uv安装依赖
uv sync配置账号
cp .env.example .env填写:
POSPAL_ACCOUNT=your_account
POSPAL_PASSWORD=your_password启动 MCP
默认暴露精简工具集(42 个)。需要原始层重叠查询时设置:
export POSPAL_MCP_PROFILE=advanced # 额外暴露 login / business_summary 等STDIO:
uv run fastmcp run server.py:mcpHTTP:
uv run fastmcp run server.py:mcp --transport http --port 8000Python SDK 示例
from fastpospal.client import PospalClient
from fastpospal.service import PospalService
client = PospalClient(account, password)
client.login()
svc = PospalService(client)
print(svc.product_summary())MCP 使用示例
在 Cursor 或 Claude Desktop 中:
查询今天商品总数
搜索条码 6901234567890
创建一个测试商品
Agent 将自动调用对应 MCP 工具。
远程 HTTP 部署(Nginx + Docker)
适用于 OPC Feed、Cursor 等通过 HTTPS 远程连接 MCP。
配置
.env:POSPAL_*、MCP_AUTH_TOKEN,以及公网域名白名单:FASTMCP_HTTP_ALLOWED_HOSTS=["your-domain.com"]经 Nginx 反代时 必须 设置,否则 Bearer 鉴权通过后 FastMCP 会因
Host校验返回 421 Misdirected Request。启动容器:
docker compose -f deploy/docker-compose.prod.yml up -dNginx 反代 不要用尾斜杠(
/pospal/mcp而非/pospal/mcp/),否则 FastMCP 会 307 到错误路径。萌萌书店示例见deploy/nginx-mmsd-pospal-mcp.conf。客户端 MCP URL 与 Nginx location 保持一致,例如
https://mmsd.site/pospal/mcp。
发布到生产(GitHub Actions)
主路径:push 到 main 后,在 haqyd self-hosted runner 上自动 patch bump → 构建镜像 → SSH docker load → 覆盖服务器 .env → compose 重启(避免 GitHub 托管 runner 跨国传镜像过慢)。
首次或密钥变更时,在本机同步 Secrets(需已 gh auth login):
# .env 中需有 POSPAL_*、MCP_AUTH_TOKEN、DEPLOY_HOST(及可选 DEPLOY_USER)
# SSH 私钥默认读 ~/.ssh/id_rsa,可用 DEPLOY_SSH_KEY_FILE 覆盖
bash scripts/sync-gh-secrets.sh之后:
git push origin main在仓库 Actions 查看 Deploy workflow。手动补跑:Actions → Deploy → Run workflow。
紧急本机发布(不走 CI):bash deploy/push-image.sh(本机脚本不会覆盖服务器 .env)。
架构
AI Agent
(Cursor / Claude)
│
▼
FastPospal MCP
│
FastPospal SDK
│
PosPal WebRoadmap
登录与会话管理
商品管理
分类管理
会员管理
库存查询
HTTP MCP
CLI
PyPI 发布
自动化测试
官方 OpenAPI 适配
参与贡献
提交 Issue 时可选择 Bug 报告 或 功能建议 模板。
License
MIT
Available Tools
28 toolspospal_create_categoryA
【写】创建商品分类。parent_name 为空则创建顶级分类。
Inputs: name (required), parent_name. Returns: object
pospal_create_customerC
【写】创建会员。number 为会员卡号(删除后不可复用)。
Inputs: name (required), number (required), tel, remarks. Returns: object
pospal_create_productC
【写】创建测试商品。barcode 为空则自动生成;category_uid 为空则用第一个分类。
Inputs: name (required), barcode, buy_price, sell_price, +1 more. Returns: object
pospal_delete_categoriesB
【写】批量删除分类(category_uids 为 uid 字符串列表)。
Inputs: category_uids (required). Returns: object
pospal_delete_customerB
【写】软删除会员(enable=-1,卡号不可复用)。
Inputs: number (required). Returns: object
pospal_delete_productA
【写】删除商品(不可恢复,仅测试账号使用)。
Inputs: product_id (required). Returns: object
pospal_find_customerB
按会员卡号/手机号查会员详情 JSON。
Inputs: number (required). Returns: object
pospal_find_product_by_barcodeB
按条码查商品详情。
Inputs: barcode (required). Returns: object
pospal_get_customer_extrasC
查会员附属信息:次卡、权益卡、购物卡、优惠券。
Inputs: number (required). Returns: object
pospal_get_productC
按 productId 获取商品详情 JSON。
Inputs: product_id (required). Returns: object
pospal_list_categoriesA
获取商品分类树(JSON)。
Inputs: no named parameters. Returns: result
pospal_list_customersB
分页查会员列表。customer_type: 1=启用, 0=禁用, 2=过期。
Inputs: keyword, page_size, page_index, customer_type. Returns: object
pospal_list_eshop_ordersC
分页查自营网单。
Inputs: end_time (required), begin_time (required), keyword, page_size, +1 more. Returns: object
pospal_list_product_purchasesC
分页查采购单。
Inputs: end_time (required), begin_time (required), keyword, page_size, +1 more. Returns: object
pospal_list_productsC
分页查询商品列表(HTML 解析为结构化数据)。
Inputs: enable, keyword, page_size, page_index. Returns: object
pospal_list_stockC
分页查库存列表(全店商品库存汇总)。
Inputs: keyword, page_size, page_index. Returns: object
pospal_list_stock_flowsB
分页查货流单(进货/出库/调拨)列表。
Inputs: end_time (required), begin_time (required), page_size, page_index. Returns: object
pospal_list_suppliersB
获取供应商下拉列表(JSON)。
Inputs: no named parameters. Returns: result
pospal_list_ticketsC
分页查销售单据。ticket_type: 0=有效, 1=作废, 4=退货, 2=会员, 3=批发。
Inputs: end_time (required), begin_time (required), sn, page_size, +2 more. Returns: object
pospal_loginA
强制重新登录银豹云后台,刷新会话 cookie。
Inputs: no named parameters. Returns: object
pospal_openapi_statusB
检查银豹官方开放平台 appId/appKey 是否已配置。
Inputs: no named parameters. Returns: object
pospal_product_summaryC
商品数量统计。keyword 支持条码/名称/拼音码。
Inputs: enable, keyword. Returns: object
pospal_session_infoA
查看当前银豹登录会话(门店子域、userId、是否有效)。
Inputs: no named parameters. Returns: object
pospal_set_product_stock_limitA
【写】设置商品库存上下限(不直接改库存数量)。
Inputs: product_uid (required), max_stock, min_stock. Returns: object
pospal_stock_change_historyC
查指定商品条码的库存变更流水。
Inputs: barcode (required), end_time (required), begin_time (required). Returns: object
pospal_update_categoryC
【写】重命名分类。
Inputs: new_name (required), category_uid (required), parent_name. Returns: object
pospal_update_customerC
【写】更新会员资料。余额/积分修改需门店开启 editMoneyPoint 权限。
Inputs: number (required), tel, name, remarks. Returns: object
pospal_update_productA
【写】更新商品字段(仅传需要修改的字段)。
Inputs: product_id (required), name, enable, buy_price, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 28 tools
Each tool targets a distinct entity and action (e.g., create vs. list vs. delete for categories, customers, products). There is no overlap in functionality; even search tools are differentiated by query parameters (barcode vs. customer number).
Most tools follow the pospal_verb_noun pattern (e.g., pospal_create_category, pospal_list_products), but a few deviate (pospal_login, pospal_openapi_status, pospal_session_info) breaking the pattern slightly.
28 tools cover a wide range of POS operations (categories, customers, products, stock, orders, tickets, suppliers) without being excessive. Each tool serves a clear purpose and the count is appropriate for the domain.
The tool set provides CRUD for core entities (categories, customers, products) and read-only access for orders, purchases, stock, and tickets. Missing create operations for some entities (e.g., suppliers, purchase orders) are minor gaps that agents can work around.
Maintenance
Related MCP Connectors
Build custom POS apps with your AI agent. Final's MCP server gives developers what they need to ship a custom point of sale: scaffold a checkout flow, adapt vetted screen blueprints for counter POS, self-checkout kiosks, restaurant ordering and payment terminals, ground every call in Final's version-locked POS APIs, validate, boot a live preview and deploy to real hardware with integrated card payments. The same server also manages the store behind it: products, stock, orders, customers and sales reports. Remote Streamable HTTP with OAuth 2.1.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that enables LLM agents to interact with PyerP ERP systems via a REST API. It allows users to search, read, create, and update ERP records such as inventory, clients, and users using natural language.-
- AlicenseAqualityDmaintenanceAn open-source MCP server that wraps the Shopline Open API into 143 AI-callable tools for e-commerce data analysis, enabling AI agents to query orders, products, inventory, customer behavior, and promotions from Shopline stores through natural language.10021MIT
- AlicenseBqualityBmaintenanceMCP server that wraps the GunStore-POS Frappe REST API, enabling AI agents to manage production settings, item pricing, records, and ATF operations via natural language commands.771GPL 3.0
- FlicenseCqualityDmaintenanceMCP server for the BILLZ POS/Retail API 2.0, enabling AI agents to perform analytics and full retail operations including sales, products, customers, reports, and inventory management.18-