Skip to main content
Glama

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

HTTP:

uv run fastmcp run server.py:mcp --transport http --port 8000

Python 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。

  1. 配置 .env:POSPAL_*、MCP_AUTH_TOKEN,以及公网域名白名单:

    FASTMCP_HTTP_ALLOWED_HOSTS=["your-domain.com"]

    经 Nginx 反代时 必须 设置,否则 Bearer 鉴权通过后 FastMCP 会因 Host 校验返回 421 Misdirected Request。

  2. 启动容器:docker compose -f deploy/docker-compose.prod.yml up -d

  3. Nginx 反代 不要用尾斜杠(/pospal/mcp 而非 /pospal/mcp/),否则 FastMCP 会 307 到错误路径。萌萌书店示例见 deploy/nginx-mmsd-pospal-mcp.conf。

  4. 客户端 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 Web

Roadmap

  • 登录与会话管理

  • 商品管理

  • 分类管理

  • 会员管理

  • 库存查询

  • HTTP MCP

  • CLI

  • PyPI 发布

  • 自动化测试

  • 官方 OpenAPI 适配


参与贡献

提交 Issue 时可选择 Bug 报告 或 功能建议 模板。


License

MIT

Available Tools

28 tools
pospal_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

    B3.2/5.0

    Scored across 28 tools

    Disambiguation5/5

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

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      An 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.
      -
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      100
      21
      MIT
    • F
      license
      C
      quality
      D
      maintenance
      MCP 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
      -