Skip to main content
Glama
ironfrancis

FastPospal

by ironfrancis
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

为什么选择 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

Install Server
A
license - permissive license
B
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • FastMCP

    wanderingnature
    A
    license
    -
    quality
    D
    maintenance
    FastMCP is a comprehensive MCP server allowing secure and standardized data and functionality exposure to LLM applications, offering resources, tools, and prompt management for efficient LLM interactions.
    3
    MIT

  • McpLLMServer

    lhmpaiPublic
    F
    license
    -
    quality
    D
    maintenance
    A FastAPI-based MCP server that enables LLM agents to interact with Ollama models through standardized MCP tools, with optional MySQL and Redis integration for data persistence and caching.

  • PyerP MCP Server

    vvbv
    F
    license
    -
    quality
    -
    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.

View all related MCP servers

Related MCP Connectors

  • Final POS

    Build custom POS, kiosk, self-checkout & in-person payment apps with AI agents on Final POS.

  • shipmail-mcp

    Shipmail MCP server for AI agent custom-domain email inboxes with REST API and webhooks.

  • DepScope

    Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ironfrancis/FastPospalMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server