MCP Shopline

An open-source MCP (Model Context Protocol) server that wraps the Shopline Open API into 19 AI-callable tools 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

19 ready-to-use tools covering orders, products, inventory, customer analytics, and promotions
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 19 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"
      }
    }
  }
}

Tools (19)

Orders (7)

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

Products & Inventory (6)

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

Analytics (6)

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

API Endpoint Coverage

Based on Shopline Open API v1:

Endpoint	Status	Notes
Orders	200	Full access
Products	200	Full access
Warehouses	200	Full access
Categories	200	Full access
Return Orders	200	Full access
Promotions	200	Full access
Product Stocks	200	Per-warehouse breakdown
Customers	403	Requires additional permissions
Channels	422/403	Not needed (store info embedded in order data)

Note: Endpoint availability depends on your Shopline API token permissions. The status above reflects a typical merchant setup. If you have broader permissions, additional endpoints may work.

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 tools (7)
│   ├── product_tools.py       # Product/inventory tools (6)
│   ├── analytics_tools.py     # Analytics tools (6)
│   └── tool_registry.py       # Unified tool registry
├── tests/
│   └── test_all_tools.py      # E2E tests for all 19 tools
└── scripts/auth/
    ├── test_connection.py     # API connection validator
    └── inspect_data_structure.py  # API response structure explorer

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

python tests/test_all_tools.py
python scripts/auth/test_connection.py

Adding a New Tool

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

Roadmap

Add Customers API tools (member profiles, demographics, membership tiers)
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
Support for multiple Shopline stores (multi-token)
Add webhook support for real-time order notifications

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