mcp-shopline 0.3.0

MCP server wrapping the Shopline Open API into 143 AI Agent-callable tools for e-commerce data analysis

MCP Shopline

繁體中文

An open-source MCP (Model Context Protocol) server that wraps the Shopline Open API into 143 AI-callable tools (75 read + 68 write) for e-commerce data analysis.

Built for Claude Code, Claude Cowork, and any MCP-compatible AI client. Enables AI agents to query orders, products, inventory, customer behavior, and promotions from Shopline stores through natural language.

What This Does

• 143 ready-to-use tools covering orders, products, inventory, customers, promotions, categories, subscriptions, conversations, reviews, and more
• MCP server (stdio JSON-RPC 2.0) — plug into Claude Code and start asking questions immediately
• Zero external dependencies beyond Python 3.9+ standard library and requests
• Built-in pagination, retry, and rate limiting — tools handle all API complexity internally
• Designed for AI agents — structured JSON output with natural language-friendly parameters (dates as YYYY-MM-DD, not timestamps)

API Reference

This project is built on the Shopline Open API v1.

• API Documentation: https://open-api.docs.shoplineapp.com
• Authentication: Bearer token via Shopline merchant admin
• Base URL: https://open.shopline.io/v1/

You need a valid Shopline API access token from a Shopline merchant account. Refer to the Shopline API authentication guide for how to obtain one.

---

Quick Start

Install

pip install mcp-shopline

Or use uvx (no install needed):

uvx --from mcp-shopline mcp-shopline

Set your API token:

export SHOPLINE_API_TOKEN=your_token_here

Use with Claude Code

Add the server via the Claude CLI:

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

Or with the environment variable inline:

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

If you clone the repo locally, the .mcp.json config will be auto-detected by Claude Code and all 143 tools become available immediately.

Use with Claude Desktop

Add to your claude_desktop_config.json:

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

Or with uvx:

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

---

Important: Write Tools

This server includes tools that create, update, and delete data in your Shopline store. Your API token's permission scope controls which operations are available.

• Review your token permissions in Shopline merchant admin
• Restrict to only the scopes you need
• Write tools are clearly marked with [WRITE] prefix in their descriptions
• Write tests require SHOPLINE_TEST_WRITES=1 to run

---

Tools (143)

Read Tools (75)

Orders (12)

Tool	Description
query_orders	Query orders by date, status, channel, store
get_sales_summary	Revenue, AOV, item price, payment/delivery breakdown
get_top_products	Product sales ranking by quantity or revenue
get_sales_trend	Daily/weekly/monthly sales trend data
get_channel_comparison	Compare performance across stores/channels
get_order_detail	Full order detail with line items
get_refund_summary	Return order statistics and refund amounts
get_archived_orders	Query archived/closed orders
get_order_labels	List labels attached to orders
get_order_tags	List tags attached to orders
get_order_action_logs	Retrieve action/audit logs for an order
get_order_transactions	Payment transaction records for an order

Products & Inventory (9)

Tool	Description
get_product_list	Search products by keyword, brand
get_product_variants	SKU variants with size x color matrix
get_inventory_overview	Total inventory summary by brand
get_low_stock_alerts	Low stock / out-of-stock SKU alerts
get_warehouses	List all warehouses and store locations
get_stock_by_warehouse	Per-warehouse stock distribution matrix
get_locked_inventory	View inventory locked by pending orders
list_purchase_orders	List purchase/replenishment orders
get_purchase_order_detail	Full detail of a single purchase order

Analytics (11)

Tool	Description
get_rfm_analysis	Customer RFM segmentation
get_repurchase_analysis	Repurchase rate and cycle analysis
get_customer_geo_analysis	Customer geographic distribution
get_inventory_turnover	Stock turnover rate and days
get_category_sales	Sales breakdown by product category
get_promotion_analysis	Promotion campaign effectiveness
get_refund_by_store	Return order breakdown by store/channel
get_stock_transfer_suggestions	Auto-generate inter-warehouse transfer recommendations
get_promotion_roi	Cross-reference promotion periods with sales trend to calculate lift and ROI
get_customer_lifecycle	Compare RFM segments across two periods to track customer migration
get_slow_movers	Identify products with high inventory but low sales for clearance planning

Customers (9)

Tool	Description
list_customers	Search and list customer profiles
get_customer_profile	Full profile for a single customer
list_customer_groups	List customer segmentation groups
get_customer_group_members	Members within a customer group
list_store_credits	Store credit balances and history
list_membership_tiers	Membership tier definitions
get_customer_tier_history	Tier upgrade/downgrade history for a customer
list_member_point_rules	Point earning and redemption rules
list_custom_fields	Custom field definitions for customer profiles

Categories & Promotions (14)

Tool	Description
get_category_tree	Full category hierarchy tree
get_category_detail	Detail for a single category
list_promotions	List all promotion campaigns
get_promotion_detail	Full detail for a single promotion
search_promotions	Search promotions by keyword or status
list_flash_price_campaigns	List flash sale / limited-time price campaigns
get_flash_price_campaign_detail	Detail for a single flash price campaign
list_affiliate_campaigns	List affiliate marketing campaigns
get_affiliate_campaign_detail	Detail for a single affiliate campaign
get_affiliate_campaign_usage	Usage and performance stats for an affiliate campaign
list_gifts	List gift-with-purchase promotions
list_addon_products	List add-on product promotions
list_product_subscriptions	List product subscription plans
get_product_subscription_detail	Detail for a single subscription plan

Order Extended (8)

Tool	Description
list_return_orders	List return/refund orders
get_return_order_detail	Full detail for a single return order
get_order_delivery	Delivery tracking and logistics info for an order
list_conversations	List customer service conversations
get_conversation_messages	Messages within a conversation thread
list_product_reviews	List product reviews
get_product_review_detail	Full detail for a single product review

Store Settings (12)

Tool	Description
list_merchants	List merchant accounts
get_merchant_detail	Detail for a single merchant
list_payments	List configured payment methods
list_delivery_options	List configured delivery options
get_delivery_option_detail	Detail for a single delivery option
get_delivery_time_slots	Available delivery time slots
list_channels	List sales channels (online, POS, etc.)
get_channel_detail	Detail for a single channel
get_app_settings	App-level configuration settings
list_taxes	List tax configurations
get_staff_permissions	Staff account permission settings
get_token_info	Info and scope of the current API token
list_agents	List customer service agent accounts

---

Write Tools (68)

Write tools are marked with [WRITE] in their descriptions. They require appropriate token permissions and SHOPLINE_TEST_WRITES=1 to run in tests.

Domain	Tools
Order Operations	8 tools — update status, add notes, assign labels/tags, cancel, fulfill
Customer Operations	6 tools — create/update customer, adjust store credits, update group membership
Product Operations	15 tools — create/update/delete products, manage variants, update stock
Promotion/Coupon/Campaign Operations	12 tools — create/update/delete promotions, coupons, flash sales, affiliate campaigns
Category Operations	3 tools — create, update, delete categories
Return Order Operations	2 tools — approve/reject return orders
Conversation Operations	2 tools — reply to conversations, update conversation status
Review Operations	6 tools — reply to reviews, approve/reject/hide reviews
Gift/Addon Operations	7 tools — create/update/delete gift and add-on promotions
Purchase Order Operations	2 tools — create and receive purchase orders
Media/Metafield Operations	2 tools — upload media, set metafields
Delivery/Merchant Operations	3 tools — update delivery info, manage merchant settings

---

API Endpoint Coverage

Based on Shopline Open API v1:

Endpoint	Status	Notes
Orders	200	Full access (read + write)
Products	200	Full access (read + write)
Warehouses	200	Full access
Categories	200	Full access (read + write)
Return Orders	200	Full access (read + write)
Promotions	200	Full access (read + write)
Product Stocks	200	Per-warehouse breakdown
Customers	200	Full access (read + write)
Channels	200	Full access
Conversations	200	Customer service threads (read + write)
Reviews	200	Product reviews (read + write)
Subscriptions	200	Product subscription plans
Affiliate Campaigns	200	Affiliate marketing (read + write)
Flash Price Campaigns	200	Flash sales (read + write)
Purchase Orders	200	Replenishment orders (read + write)
Gifts & Add-ons	200	Gift-with-purchase promotions (read + write)
Store Settings	200	Payments, delivery, taxes, staff permissions

Note: Endpoint availability depends on your Shopline API token permissions. The status above reflects full-permission access. Restrict your token to only the scopes you need.

---

Project Structure

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 Constraints

These are Shopline Open API limitations handled internally by the tools:

• Pagination: page + per_page (max 50), 0.2s delay between pages for rate limiting
• Search limit: 10,000 results max; fetch_all_pages_by_date_segments() splits large queries by date range
• Order status: online orders use confirmed, POS uses completed — tools include both by default
• Channel identification: created_from = "shop" (online) / "pos" (retail); store name from order.channel.created_by_channel_name
• Currency: all monetary values in TWD (New Taiwan Dollar), returned as float via money_to_float()

---

Development

Setup from Source

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

Run Tests

# 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

Adding a New Tool

1. Define a schema dict (Claude API tool_use format with name, description, input_schema)
2. Implement the function using api_get / fetch_all_pages from base_tool.py
3. Append {"schema": ..., "function": ...} to the module's tool list
4. Auto-registered via tool_registry.py and mcp_server.py — no extra wiring needed

---

Known Test Gaps

The following tools are implemented and registered but have not been fully E2E tested due to test-store data or token-scope limitations. They compile correctly, import successfully, and follow all project conventions — they just need real data or broader token permissions to verify end-to-end.

Requires store data (create via Shopline admin)

Tool	What's needed
get_flash_price_campaign_detail	A flash price campaign (create in Shopline admin > Marketing > Flash Sale)
get_affiliate_campaign_usage	An affiliate campaign that has been used in at least one order
get_product_subscription_detail	A product with subscription enabled (configure in admin > Products)
get_return_order_detail	A completed return order (create via admin > Orders > Returns)
get_order_delivery	An order with shipment executed (delivery has its own ID after shipment)
get_customer_group_members	At least one customer group (create via admin > Customers > Groups)
get_customer_tier_history	A customer with membership tier changes (requires tier rules configured)
get_delivery_time_slots	A delivery option with time slots configured

Requires token permissions

Tool	Required scope
list_conversations / get_conversation_messages	Conversations read permission
list_channels / get_channel_detail	Channels read permission (commonly returns 403/422; channel info is also available via order.channel.created_by_channel_name)

Write tools

All 68 write tools have been verified at the import/registration level. Full E2E write tests require SHOPLINE_TEST_WRITES=1 and a dedicated test store to avoid modifying production data. See tests/test_writes/ for gated test scripts.

Roadmap

• get_refund_by_store — return order breakdown by store/channel
• get_stock_transfer_suggestions — auto-generate inter-warehouse transfer recommendations based on sales velocity and stock levels
• get_category_tree — standalone category structure viewer
• get_promotion_roi — cross-reference promotion periods with sales trend data to calculate lift and ROI
• get_customer_lifecycle — compare RFM segments across two periods to track customer migration (upgrade/churn)
• get_slow_movers — identify products with high inventory but low sales for clearance planning
• Customers API tools (member profiles, demographics, membership tiers)
• Support for multiple Shopline stores (multi-token)
• Add webhook support for real-time order notifications

---

Usage Examples

"What were my sales this month?"

You: 這個月的銷售摘要是什麼？

AI calls:

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

Result: 本月營業額 NT$1,234,567，共 456 筆訂單，客單價 NT$2,707，線上佔 62%、門市佔 38%。

---

"Which products are selling best?"

You: 上個月最暢銷的前 5 名商品是什麼？

AI calls:

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

Result: 第一名「經典帆布休閒鞋 Classic Canvas」營收 NT$892,000（268 雙），第二名「輕量機能防風外套」營收 NT$654,000...

---

"Tell me about this customer"

You: 幫我查一下客戶「陳大明」的完整資訊

AI calls:

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

Result: 陳大明，VIP 會員，累計消費 NT$56,330，近 30 天消費 5 次，會員點數餘額 2,800 點，儲值金餘額 NT$500。

---

"Any products running low on stock?"

You: 哪些商品快缺貨了？

AI calls:

get_low_stock_alerts(threshold = 5)

Result: 共 3,098 個 SKU 低於門檻，其中 2,847 個已完全缺貨。最嚴重的是「經典帆布休閒鞋 Classic Canvas」深藍色 M 號（庫存 0）。

---

"Compare online vs. retail performance"

You: 比較一下線上和門市這個月的業績

AI calls:

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

Result: 線上官網營收 NT$780,000（佔 63%），信義旗艦店 NT$220,000（佔 18%），中山概念店 NT$120,000（佔 10%）...

---

"Who are my best customers vs. churning ones?"

You: 分析一下客戶 RFM 分群

AI calls:

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

Result: 共 1,618 位客戶。最佳客戶 70 人（HHH），近期新客 433 人（HLL），流失高消費客戶 188 人（LLH）需要挽回。

---

"Create a new customer" (Write tool)

You: 幫我建立一個新客戶，姓名王小明，email [e-mail]

AI calls:

create_customer(
  name = "王小明",
  email = "[e-mail]"
)

Result: [WRITE] 客戶王小明建立成功，ID: 69d77d57...

---

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

When adding new tools, follow the existing pattern in tools/ and ensure the tool passes the E2E test suite.

License

MIT