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 shopline-mcp

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 -- shopline-mcp

Or with the environment variable inline:

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

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": "shopline-mcp",
      "env": {
        "SHOPLINE_API_TOKEN": "your_token_here"
      }
    }
  }
}

Or with uvx:

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

Tools (19)

Orders (7)

Products & Inventory (6)

Analytics (6)

API Endpoint Coverage

Based on Shopline Open API v1:

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

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

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