mcp-shopline

# MCP Shopline [](https://pypi.org/project/mcp-shopline/) [](https://pypi.org/project/mcp-shopline/) [](https://opensource.org/licenses/MIT) [](https://github.com/asgard-ai-platform/mcp-shopline/stargazers) [](https://github.com/asgard-ai-platform/mcp-shopline/issues) [](https://github.com/asgard-ai-platform/mcp-shopline/commits/main) [](https://modelcontextprotocol.io/) [繁體中文](README.zh-TW.md) An open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps the [Shopline Open API](https://open-api.docs.shoplineapp.com/docs/getting-started) into 143 AI-callable tools (75 read + 68 write) for e-commerce data analysis. Built for [Claude Code](https://claude.ai/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](https://open-api.docs.shoplineapp.com/docs/getting-started). - 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](https://open-api.docs.shoplineapp.com/docs/authentication) for how to obtain one. --- ## Quick Start ### Install ```bash pip install mcp-shopline ``` Or use uvx (no install needed): ```bash uvx --from mcp-shopline mcp-shopline ``` Set your API token: ```bash export SHOPLINE_API_TOKEN=your_token_here ``` ### Use with Claude Code Add the server via the Claude CLI: ```bash claude mcp add --transport stdio shopline -- mcp-shopline ``` Or with the environment variable inline: ```bash 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`: ```json { "mcpServers": { "shopline": { "command": "mcp-shopline", "env": { "SHOPLINE_API_TOKEN": "your_token_here" } } } } ``` Or with uvx: ```json { "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](https://open-api.docs.shoplineapp.com): | Endpoint | Status | Notes | |----------|--------|-------| | [Orders](https://open-api.docs.shoplineapp.com/docs/order) | 200 | Full access (read + write) | | [Products](https://open-api.docs.shoplineapp.com/docs/product) | 200 | Full access (read + write) | | [Warehouses](https://open-api.docs.shoplineapp.com/docs/warehouse) | 200 | Full access | | [Categories](https://open-api.docs.shoplineapp.com/docs/category) | 200 | Full access (read + write) | | [Return Orders](https://open-api.docs.shoplineapp.com/docs/return-order) | 200 | Full access (read + write) | | [Promotions](https://open-api.docs.shoplineapp.com/docs/promotion) | 200 | Full access (read + write) | | [Product Stocks](https://open-api.docs.shoplineapp.com/docs/product-stock) | 200 | Per-warehouse breakdown | | [Customers](https://open-api.docs.shoplineapp.com/docs/customer) | 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 ```bash git clone https://github.com/asgard-ai-platform/mcp-shopline.git cd mcp-shopline pip install -e . ``` ### Run Tests ```bash # 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 - [x] `get_refund_by_store` — return order breakdown by store/channel - [x] `get_stock_transfer_suggestions` — auto-generate inter-warehouse transfer recommendations based on sales velocity and stock levels - [x] `get_category_tree` — standalone category structure viewer - [x] `get_promotion_roi` — cross-reference promotion periods with sales trend data to calculate lift and ROI - [x] `get_customer_lifecycle` — compare RFM segments across two periods to track customer migration (upgrade/churn) - [x] `get_slow_movers` — identify products with high inventory but low sales for clearance planning - [x] 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 wang@test.com **AI calls:** ``` create_customer( name = "王小明", email = "wang@test.com" ) ``` **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