Shopline Shopline 電商平台

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

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"
      }
    }
  }
}

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.

Read Tools (75)

Orders (12)

Products & Inventory (9)

Analytics (11)

Customers (9)

Categories & Promotions (14)

Order Extended (8)

Store Settings (12)

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.

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

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.

MIT

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

Based on Shopline Open API v1:

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.

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

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

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)

Requires token permissions

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.

• 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

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