sellercloud-mcp

# sellercloud-mcp

The first Model Context Protocol server for SellerCloud. Plug Claude into your catalog, inventory, orders, and channel listings — read-only, in five minutes.

Why this exists

SellerCloud has no public SDK. Their REST API is well-documented but unbranded — every team that automates against it ends up writing the same auth-and-pagination glue from scratch.

If you use Claude (or any MCP-aware AI assistant) to operate ecommerce day-to-day, that gap is the difference between "summarize today's orders" working out of the box and "summarize today's orders" requiring a custom integration.

sellercloud-mcp closes that gap. It's a tiny, well-tested, MIT-licensed MCP server that exposes seven read-only SellerCloud endpoints to any MCP client. Built from years of running ecommerce automation at scale.

What you can do with it

Wire this server into Claude Code, Claude Desktop, or any MCP host, then ask things like:

• "Search for any SKU containing WIDGET and show me the inventory levels."
• "How many orders did we ship yesterday across all marketplaces? Group by channel."
• "Pull order 100001 and tell me which line items shipped."
• "List the channels configured for company 9001 and show which ones are active."
• "For SKU ACME-001, compare the price across every channel listing."

Claude reads your catalog directly. No copy-paste, no spreadsheets, no custom pipelines.

Tools (v0.1, all read-only)

Write endpoints (create order, update inventory, push channel changes) are intentionally not in v0.1. They are planned for v0.2 once read-only ergonomics settle.

Install

pip install sellercloud-mcp

v0.1 ships from this repository. PyPI publication is pending — for now, install with pip install git+https://github.com/alveyautomation/sellercloud-mcp or clone and run pip install -e . locally.

Configure credentials

The server reads everything from environment variables. Copy .env.example to .env and fill in your tenant:

SELLERCLOUD_API_URL=https://your-team.api.sellercloud.com/rest/
SELLERCLOUD_USERNAME=your-username
SELLERCLOUD_PASSWORD=your-password
SELLERCLOUD_DEFAULT_COMPANY_ID=        # optional fallback
SELLERCLOUD_HTTP_TIMEOUT=60            # optional, seconds
SELLERCLOUD_MAX_RETRIES=3              # optional

Use a read-only SellerCloud account. v0.1 only calls GET endpoints, but defense in depth means you should hand the server a dedicated user that cannot modify anything. When v0.2 lands with write tools, opt-in by upgrading the credential — never the other way around.

Wire into Claude Code

Add to ~/.claude/claude_code_config.json (or your project's MCP config):

{
  "mcpServers": {
    "sellercloud": {
      "command": "sellercloud-mcp",
      "env": {
        "SELLERCLOUD_API_URL": "https://your-team.api.sellercloud.com/rest/",
        "SELLERCLOUD_USERNAME": "your-username",
        "SELLERCLOUD_PASSWORD": "your-password",
        "SELLERCLOUD_DEFAULT_COMPANY_ID": "9001"
      }
    }
  }
}

Restart Claude Code. The seven sellercloud_* tools will appear in any new session.

Wire into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add the same mcpServers block as above. Restart the desktop app.

Tool reference

Every tool returns a JSON envelope:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

sellercloud_search_products

sellercloud_search_products(
    query: str,                          # required
    company_id: int | None = None,       # falls back to default if unset
    page: int = 1,
    page_size: int = 50,                 # capped at 50 by SellerCloud
)

Example response:

{
  "ok": true,
  "data": {
    "items": [
      { "ID": "ACME-WIDGET-001", "ProductName": "Acme Widget, Standard", "Price": 29.99 }
    ],
    "total": 1,
    "page": 1,
    "page_size": 50
  }
}

sellercloud_get_product

sellercloud_get_product(sku: str, company_id: int | None = None)

Returns the catalog record, or data: null if the SKU is not in the company's catalog.

sellercloud_search_orders

sellercloud_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    company_id: int | None = None,
    query: str | None = None,
    limit: int = 200,                    # max 1000
)

Pagination is handled transparently — SellerCloud caps page size at 50, but the tool collects pages up to limit. The response includes limit_reached: true when there were more orders than limit allowed.

sellercloud_get_order

sellercloud_get_order(order_id: int)

Returns the full order record (with Items[]), or data: null for a 404.

sellercloud_get_inventory

sellercloud_get_inventory(sku: str, company_id: int | None = None)

The returned record includes:

• InventoryAvailableQty — what the API considers sellable right now
• PhysicalQty — on-hand
• ReservedQty — held for open orders
• OnOrder — incoming PO qty

Use InventoryAvailableQty as the canonical "qty I can sell" number.

sellercloud_list_channels

sellercloud_list_channels(company_id: int | None = None)

Returns the list of configured channel feeds for the company. Each record includes ChannelID, Name, and Active.

sellercloud_get_channel_listing

sellercloud_get_channel_listing(channel_id: int, sku: str)

Per-channel listing detail. Useful for spot-checking prices across marketplaces.

Local development

git clone https://github.com/alveyautomation/sellercloud-mcp
cd sellercloud-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 44 tests, ~4s

Pre-commit hooks (gitleaks, ruff, formatter, tenant-fingerprint scrubber):

pip install pre-commit
pre-commit install

Integration tests against a real SellerCloud sandbox account are gated behind SELLERCLOUD_INTEGRATION_TESTS=1. They are not required for normal contribution.

Troubleshooting

Failed to obtain SellerCloud token — username/password rejected. Most common cause: the account has 2FA enabled or is locked out. SellerCloud's POST /api/token endpoint expects a non-2FA service account.

Missing required environment variables — the server tried to start before its .env was loaded. Either export the vars in the parent shell, or ensure your MCP host config includes them in the env block.

Empty results despite known data — confirm the company_id is correct. SellerCloud returns only the authenticated user's default company unless you pass companyID explicitly.

Pagination feels slow — page size is capped at 50 by SellerCloud, not by us. For large date windows, expect multiple round-trips.

Contributing

Issues and pull requests welcome. Please:

• Run pytest before opening a PR (pip install -e ".[dev]").
• Run pre-commit run --all-files.
• Keep additions to v0.1 scope read-only. Write endpoints land in v0.2.
• Synthetic data only in tests — no real SKUs, customer names, or order numbers.

License

MIT — see LICENSE.

Disclaimer

sellercloud-mcp is an unofficial, third-party integration. It is not endorsed by, affiliated with, or supported by SellerCloud, Inc. "SellerCloud" is a trademark of SellerCloud, Inc. Use at your own risk; verify behavior against your tenant before depending on it for production decisions.