AI导哈

电商数据分析工具

一个开源MCP服务器，将Shopline Open API封装成143个AI可调用工具，用于电商数据分析

  • by asgard-ai-platform
  • Python
  • 本地部署
  • 20 星标
  • 更新于
在 GitHub 查看 asgard-ai-platform/mcp-shopline

使用说明

MCP商店线

繁体中文

开源 MCP（模型上下文协议） 包装的服务器 商店线开放API 将143个AI可调用工具（75个读取+68个写入）用于电子商务数据分析。

专为 克劳德代码Claude Cowork和任何兼容MCP的AI客户端。使AI代理能够通过自然语言查询Shopline商店的订单、产品、库存、客户行为和促销活动。

这有什么作用

  • 143个即用型工具 涵盖订单、产品、库存、客户、促销、类别、订阅、对话、评论等
  • MCP服务器 （stdio JSON-RPC 2.0）-插入Claude Code并立即开始提问
  • 零外部依赖 超越Python 3.9+标准库 requests
  • 内置分页、重试和速率限制 -工具内部处理所有API复杂性
  • 专为AI代理设计 --具有自然语言友好参数的结构化JSON输出（日期为 YYYY-MM-DD，不是时间戳）

API 参考

该项目建立在 商店线开放API v1.

  • API文件：https://open-api.docs.shoplineapp.com
  • 身份验证：通过Shopline商家管理员进行承载令牌
  • 基本URL: https://open.shopline.io/v1/

您需要来自Shopline商家帐户的有效Shopline API访问令牌。请参阅 车间API认证指南 如何获得一个。

快速开始

安装

pip install mcp-shopline

或者使用uvx（无需安装）：

uvx --from mcp-shopline mcp-shopline

设置API令牌：

export SHOPLINE_API_TOKEN=your_token_here

与Claude Code一起使用

通过Claude CLI添加服务器：

claude mcp add --transport stdio shopline -- mcp-shopline

或者将环境变量内联：

claude mcp add --transport stdio shopline -e SHOPLINE_API_TOKEN=your_token_here -- mcp-shopline

如果你在本地克隆仓库 .mcp.json Claude Code将自动检测配置，所有143个工具将立即可用。

与Claude Desktop一起使用

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "shopline": {
      "command": "mcp-shopline",
      "env": {
        "SHOPLINE_API_TOKEN": "your_token_here"
      }
    }
  }
}

或者使用uvx：

{
  "mcpServers": {
    "shopline": {
      "command": "uvx",
      "args": ["--from", "mcp-shopline", "mcp-shopline"],
      "env": {
        "SHOPLINE_API_TOKEN": "your_token_here"
      }
    }
  }
}

重要提示：编写工具

此服务器包括以下工具 创建、更新和删除 您的Shopline商店中的数据。 API令牌的权限范围控制哪些操作可用。

  • 在Shopline商家管理中查看您的令牌权限
  • 仅限于您需要的范围
  • 书写工具上标有 [WRITE] 在描述中添加前缀
  • 编写测试需要 SHOPLINE_TEST_WRITES=1 跑

工具（143）

阅读工具（75）

订单（12）

工具 说明
query_orders 按日期、状态、渠道、门店查询订单
get_sales_summary 收入、AOV、项目价格、付款/交货明细
get_top_products 按数量或收入划分的产品销售排名
get_sales_trend 每日/每周/每月销售趋势数据
get_channel_comparison 比较不同商店/渠道的性能
get_order_detail 包含行项目的完整订单详细信息
get_refund_summary 退货订单统计和退款金额
get_archived_orders 查询已存档/已关闭的订单
get_order_labels 列出订单附带的标签
get_order_tags 列出订单附带的标签
get_order_action_logs 检索订单的操作/审核日志
get_order_transactions 订单的付款交易记录

产品与库存（9）

工具 说明
get_product_list 按关键字、品牌搜索产品
get_product_variants 具有大小x颜色矩阵的SKU变体
get_inventory_overview 按品牌汇总的总库存
get_low_stock_alerts 库存低/缺货SKU警报
get_warehouses 列出所有仓库和存储位置
get_stock_by_warehouse 每个仓库的库存分布矩阵
get_locked_inventory 查看由待处理订单锁定的库存
list_purchase_orders 列出采购/补货订单
get_purchase_order_detail 单个采购订单的全部细节

分析（11）

工具 说明
get_rfm_analysis 客户RFM细分
get_repurchase_analysis 回购率及周期分析
get_customer_geo_analysis 客户地理分布
get_inventory_turnover 库存周转率和周转天数
get_category_sales 按产品类别划分的销售明细
get_promotion_analysis 促销活动效果
get_refund_by_store 按商店/渠道细分的退货订单
get_stock_transfer_suggestions 自动生成仓库间转移建议
get_promotion_roi 将促销期与销售趋势进行交叉引用，以计算提升率和投资回报率
get_customer_lifecycle 比较两个时期的RFM细分市场，以跟踪客户迁移
get_slow_movers 识别库存高但销售额低的产品，以制定清关计划

客户（9）

工具 说明
list_customers 搜索并列出客户资料
get_customer_profile 单个客户的完整资料
list_customer_groups 列出客户细分组
get_customer_group_members 客户群中的成员
list_store_credits 存储信用余额和历史记录
list_membership_tiers 成员级别定义
get_customer_tier_history 客户的层升级/降级历史记录
list_member_point_rules 积分赚取和兑换规则
list_custom_fields 客户配置文件的自定义字段定义

分类与促销（14）

工具 说明
get_category_tree 完整类别层次树
get_category_detail 单个类别的详细信息
list_promotions 列出所有促销活动
get_promotion_detail 单次促销的全部细节
search_promotions 按关键字或状态搜索促销活动
list_flash_price_campaigns 列出闪购/限时价格活动
get_flash_price_campaign_detail 单次闪购价格活动的详细信息
list_affiliate_campaigns 列出联盟营销活动
get_affiliate_campaign_detail 单个联盟活动的详细信息
get_affiliate_campaign_usage 联盟活动的使用情况和性能统计数据
list_gifts 列出购买促销的礼物
list_addon_products 列出附加产品促销活动
list_product_subscriptions 列出产品订阅计划
get_product_subscription_detail 单一订阅计划的详细信息

订单延期（8）

工具 说明
list_return_orders 列出退货/退款订单
get_return_order_detail 单个退货订单的完整细节
get_order_delivery 订单的交货跟踪和物流信息
list_conversations 列出客户服务对话
get_conversation_messages 对话线程中的消息
list_product_reviews 列出产品评论
get_product_review_detail 单个产品审查的全部细节

商店设置（12）

工具 说明
list_merchants 列出商家账户
get_merchant_detail 单个商家的详细信息
list_payments 列出已配置的付款方式
list_delivery_options 列出配置的交付选项
get_delivery_option_detail 单一交付选项的详细信息
get_delivery_time_slots 可用交付时间段
list_channels 列出销售渠道（在线、POS等）
get_channel_detail 单通道详图
get_app_settings 应用程序级配置设置
list_taxes 列出税务配置
get_staff_permissions 员工帐户权限设置
get_token_info 当前API令牌的信息和范围
list_agents 列出客户服务代理帐户

书写工具（68）

书写工具标有 [WRITE] 在他们的描述中。它们需要适当的令牌权限和 SHOPLINE_TEST_WRITES=1 在测试中运行。

域 工具
订单操作 8个工具——更新状态、添加注释、分配标签/标记、取消、履行
客户运营 6个工具--创建/更新客户、调整店铺积分、更新群组成员资格
产品运营 15个工具——创建/更新/删除产品、管理变体、更新库存
促销/优惠券/活动操作 12个工具--创建/更新/删除促销、优惠券、闪购、联盟活动
类别操作 3个工具--创建、更新、删除类别
退货订单操作 2个工具--批准/拒绝退货订单
对话操作 2个工具--回复对话、更新对话状态
审核操作 6个工具--回复审核、批准/拒绝/隐藏审核
礼品/附加组件操作 7个工具--创建/更新/删除礼品和附加组件促销活动
采购订单操作 2个工具--创建和接收采购订单
媒体/元字段操作 2个工具--上传媒体、设置元字段
配送/商户操作 3个工具——更新配送信息，管理商户设置

API端点覆盖率

基于 商店线开放API v1:

端点 状态 注释
订单 200 完全访问（读+写）
产品 200 完全访问（读+写）
仓库 200 完全访问
分类 200 完全访问（读+写）
退货订单 200 完全访问（读+写）
促销 200 完全访问（读+写）
产品库存 200 按仓库细分
客户 200 完全访问（读+写）
频道 200 完全访问
对话 200 客户服务线程（读+写）
评论 200 产品评论（读+写）
订阅 200 产品订阅计划
联盟营销活动 200 联盟营销（读+写）
闪购价格活动 200 闪购（读+写）
采购订单 200 补货订单（读+写）
礼品和附加组件 200 购买促销礼品（读+写）
店铺设置 200 付款、配送、税费、员工权限

注： 端点可用性取决于您的Shopline API令牌权限。上述状态反映了完全权限访问。将您的令牌限制在您需要的范围内。

项目结构

mcp-shopline/
├── mcp_server.py              # MCP Server (stdio JSON-RPC 2.0)
├── .mcp.json                  # Claude Code MCP auto-discovery config
├── .env.example               # Environment variable template
├── config/
│   └── settings.py            # API config (token from env, endpoints)
├── tools/
│   ├── base_tool.py           # Shared HTTP client (retry, pagination)
│   ├── order_tools.py         # Order read tools (12)
│   ├── product_tools.py       # Product/inventory read tools (9)
│   ├── analytics_tools.py     # Analytics read tools (11)
│   ├── customer_tools.py      # Customer read tools (9)
│   ├── category_tools.py      # Category & promotion read tools (14)
│   ├── extended_tools.py      # Order extended read tools (8)
│   ├── settings_tools.py      # Store settings read tools (12)
│   ├── writes/
│   │   ├── order_writes.py    # Order write tools (8)
│   │   ├── customer_writes.py # Customer write tools (6)
│   │   ├── product_writes.py  # Product write tools (15)
│   │   ├── promotion_writes.py # Promotion/coupon write tools (12)
│   │   ├── category_writes.py # Category write tools (3)
│   │   ├── return_writes.py   # Return order write tools (2)
│   │   ├── conversation_writes.py # Conversation write tools (2)
│   │   ├── review_writes.py   # Review write tools (6)
│   │   ├── gift_writes.py     # Gift/addon write tools (7)
│   │   ├── purchase_writes.py # Purchase order write tools (2)
│   │   ├── media_writes.py    # Media/metafield write tools (2)
│   │   └── delivery_writes.py # Delivery/merchant write tools (3)
│   └── tool_registry.py       # Unified tool registry
├── tests/
│   └── test_all_tools.py      # E2E tests for all 143 tools
└── scripts/
    ├── auth/
    │   ├── test_connection.py     # API connection validator
    │   └── inspect_data_structure.py  # API response structure explorer
    └── audit/
        └── scope_check.py     # Token scope and permission auditor

API约束

这些是由工具内部处理的Shopline Open API限制：

  • 分页: page + per_page （最大50），页面之间0.2秒的延迟用于速率限制
  • 搜索限制：最多10000个结果； fetch_all_pages_by_date_segments() 按日期范围拆分大型查询
  • 订单状态：在线订单使用 confirmed，POS使用 completed --默认情况下，这两种工具都包括在内
  • 通道标识: created_from = "shop" 在线的 "pos" （零售）；店铺名称来自 order.channel.created_by_channel_name
  • 货币：所有货币价值以TWD（新台湾元）为单位，通过 money_to_float()

发展

从源安装

git clone https://github.com/asgard-ai-platform/mcp-shopline.git
cd mcp-shopline
pip install -e .

运行测试

# Read tools (no side effects)
python tests/test_all_tools.py

# Include write tools (creates/updates/deletes data)
SHOPLINE_TEST_WRITES=1 python tests/test_all_tools.py

python scripts/auth/test_connection.py

添加新工具

  1. 定义模式dict（Claude API tool_use 格式与 name, description, input_schema)
  2. 使用实现该功能 api_get / fetch_all_pages 从 base_tool.py
  3. 追加 {"schema": ..., "function": ...} 到模块的工具列表
  4. 通过自动注册 tool_registry.py 和 mcp_server.py --无需额外布线

已知测试差距

以下工具已实施并注册，但 未经过全面的E2E测试 由于测试存储数据或令牌范围的限制。它们正确编译、成功导入并遵循所有项目约定——它们只需要真实数据或更广泛的令牌权限来进行端到端验证。

需要商店数据（通过Shopline管理员创建）

工具 需要什么
get_flash_price_campaign_detail 闪购价格活动（在Shopline管理>营销>闪购中创建）
get_affiliate_campaign_usage 已在至少一个订单中使用的联盟活动
get_product_subscription_detail 已启用订阅的产品（在管理>产品中配置）
get_return_order_detail 已完成的退货订单（通过管理员>订单>退货创建）
get_order_delivery 已执行发货的订单（发货后发货有自己的ID）
get_customer_group_members 至少一个客户组（通过管理员>客户>组创建）
get_customer_tier_history 会员级别更改的客户（需要配置级别规则）
get_delivery_time_slots 配置了时隙的交付选项

需要令牌权限

工具 所需范围
list_conversations / get_conversation_messages 对话读取权限
list_channels / get_channel_detail 频道读取权限（通常返回403/422；频道信息也可通过 order.channel.created_by_channel_name)

编写工具

所有68个写入工具都已在导入/注册级别进行了验证。完整的E2E写入测试需要 SHOPLINE_TEST_WRITES=1 以及一个专用的测试存储，以避免修改生产数据。看 tests/test_writes/ 用于门控测试脚本。

路线图

  • [x] get_refund_by_store --按商店/渠道细分的退货订单
  • [x] get_stock_transfer_suggestions --根据销售速度和库存水平自动生成仓库间转移建议
  • [x] get_category_tree --独立类别结构查看器
  • [x] get_promotion_roi --将促销期与销售趋势数据进行交叉引用，以计算提升率和投资回报率
  • [x] get_customer_lifecycle --比较两个时期的RFM细分市场，以跟踪客户迁移（升级/流失）
  • [x] get_slow_movers --识别库存高但销售额低的产品以进行清关计划
  • [x] 客户API工具（会员档案、人口统计、会员等级）
  • []支持多个Shopline商店（多代币）
  • []为实时订单通知添加webhook支持

用法示例

“我这个月的销售额是多少？”

你： 这个月的销售摘要是什么？

AI呼叫：

get_sales_summary(
  start_date = "2026-04-01",
  end_date = "2026-04-09",
  channel = "all"
)

结果： 本月营业额NT$1,234,567，共456笔订单，客单价NT$2,707，在线占62%、门市占38%。

“哪些产品卖得最好？”

你： 上个月最畅销的前5名商品是什么？

AI呼叫：

get_top_products(
  start_date = "2026-03-01",
  end_date = "2026-03-31",
  top_n = 5,
  sort_by = "revenue"
)

结果： 第一名「经典帆布休闲鞋Classic Canvas」营收NT$892,000（268双），第二名「轻量机能防风外套」营收NT$654,000…

“告诉我这个客户的情况”

你： 帮我查一下客户「陈大明」的完整信息

AI呼叫：

list_customers(search_keyword = "陳大明")
→ get_customer_profile(customer_id = "5f3a8b2c...")

结果： 陈大明，VIP会员，累计消费NT$56,330，近30天消费5次，会员点数余额2,800点，储值金余额NT$500。

“有库存不足的产品吗？”

你： 哪些商品快缺货了？

AI呼叫：

get_low_stock_alerts(threshold = 5)

结果： 共3,098个SKU低于门坎，其中2,847个已完全缺货。最严重的是「经典帆布休闲鞋Classic Canvas」深蓝色M号（库存0）。

“比较在线与零售业绩”

你： 比较一下在线和门市这个月的业绩

AI呼叫：

get_channel_comparison(
  start_date = "2026-04-01",
  end_date = "2026-04-09"
)

结果： 在线官网营收NT$780,000（占63%），信义旗舰店NT$220,000（占18%），中山概念店NT$120,000（占10%）...

“谁是我最好的客户，谁是流失的客户？”

你： 分析一下客戶 RFM 分群

AI呼叫：

get_rfm_analysis(
  start_date = "2026-01-01",
  end_date = "2026-04-09"
)

结果： 共1,618位客户。最佳客户70人（HHH），近期新客433人（HLL），流失高消费客户188人（LLH）需要挽回。

“创建新客户”（编写工具）

你： 帮我建立一个新客户，姓名王小明，email wang@test.com

AI呼叫：

create_customer(
  name = "王小明",
  email = "wang@test.com"
)

结果： [WRITE] 客户王小明建立成功，ID: 69d77d57...

贡献

欢迎投稿！请打开问题或提交拉取请求。

添加新工具时，请遵循中的现有模式 tools/ 并确保该工具通过E2E测试套件。

许可证

麻省理工学院

相关 MCP