sellerchamp-mcp

FastMCP HTTP server exposing SellerChamp inventory management as Model Context Protocol (MCP) tools. A single daemon process serves multiple Claude clients — Claude Desktop, Claude Code, and OpenClaw — simultaneously over a local HTTP endpoint.

Architecture

The service uses a hybrid data model designed to balance freshness against rate limits.

MCP Clients (Claude Desktop / Claude Code / OpenClaw)
        |
        v
  HTTP POST 127.0.0.1:18790/mcp
        |
        v
  FastMCP Router (stateless HTTP, JSON responses)
        |
   +---------+----------+
   |                    |
   v                    v
SQLiteReader         SellerChampAPI
(cached reads)       (live API)
   |                    |
sellerchamp_         - Single-item lookups
inventory.db         - All writes
(updated by          - Bulk operations
 db-sync job)

Bulk reads — served from a local SQLite database maintained by a companion db-sync service (daily full sync at 3 AM, orders refresh every 2 hours). Tools that default to cached reads accept a source parameter: "cached", "live", or "" (auto).

Single-item lookups and all writes — always routed to the live SellerChamp API.

Rate limiter — sliding window shared with the db-sync service. Interactive calls: 90 req/60s. Bulk calls: 60 req/60s. The server-side limit is 120 req/60s. 429 responses are handled by the pacer, not urllib3 retries, to avoid feedback loops. 5xx errors retry with exponential backoff (up to 3 times).

Confirmation gates — sellerchamp_delete_product requires confirm=True. Bulk update tools require confirm=True for batches larger than 50 items.

Tool Inventory

24 tools across four categories.

Read tools

Write tools

Bulk write tools

Destructive tools

Connecting a Client

The server binds to 127.0.0.1:18790 and runs as a macOS launchd daemon. Any MCP-compatible client on the same machine can connect with:

{
  "mcpServers": {
    "sellerchamp": {
      "url": "http://127.0.0.1:18790/mcp"
    }
  }
}

Add this block to Claude Desktop's claude_desktop_config.json or to a Claude Code project's MCP configuration. OpenClaw and other HTTP MCP clients use the same URL.

Setup

Prerequisites: Python 3.12+, a SellerChamp account with API access.

git clone https://github.com/WowWashington/sellerchamp-mcp.git
cd sellerchamp-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Create a .env file (do not commit):

SELLERCHAMP_API_TOKEN=your_token_here
SQLITE_DB_PATH=/path/to/sellerchamp_inventory.db
MCP_HOST=127.0.0.1
MCP_PORT=18790

Run directly:

python server.py

Production (macOS launchd): install a plist at ~/Library/LaunchAgents/com.sellerchamp-mcp.plist pointing to python server.py. Logs land at ~/Library/Logs/sellerchamp-mcp/.

SQLite cache: the SQLITE_DB_PATH database is maintained by a separate sellerchamp-db-sync companion service. Without it, the server falls back to the live API for all reads. The service logs a warning at startup if the cache file is not found.

Security

• Localhost-only binding — the server listens on 127.0.0.1 only. No network exposure, no authentication required.

• Confirmation gates — destructive and bulk operations require an explicit confirm=True parameter. A first call without it returns a description of what would happen.

• Read-only SQLite connections — PRAGMA query_only=ON prevents accidental writes. WAL mode allows safe concurrent reads while the sync service writes.

• Parameterized queries — all SQLite queries use bound parameters; no string interpolation of user input.

• No secrets in code — API token is read from environment at startup.

Stack

• FastMCP — MCP server framework with Streamable HTTP transport

• requests — SellerChamp API client

• SQLite (stdlib) — local inventory cache

• Python 3.12