Visceral Consignment MCP Server

Official MCP server for the Visceral Consignment external API v1 — lets Claude (or any MCP client) answer questions about a shop's consignors, payouts, and payout line items in plain English.

Read-only. Every tool call is an authenticated HTTPS request to the external REST API (/api/external/v1/), so the shop's API-key scoping, tenant isolation, rate limits, usage metering, and secure-field masking all apply unchanged. Bank details and other secure fields are always masked and cannot be revealed through this server.

Prerequisites

1. The external API enabled for the shop (pilot: enabled by Visceral support).
2. A read-only API key: in Visceral, Settings → API → Create key. Name it for the tool that will use it (e.g. "Claude assistant") — usage is tracked per key and you can revoke it independently at any time.

Configuration

Install & run

With uv (recommended — installs in one command and manages its own Python, so no Python setup is needed):

uvx visceral-consignment-mcp

Or with pip:

pip install visceral-consignment-mcp
visceral-mcp

The server speaks MCP over stdio (the standard transport for desktop clients).

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "visceral-consignment": {
      "command": "uvx",
      "args": ["visceral-consignment-mcp"],
      "env": {
        "VISCERAL_API_KEY": "vsk_your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add visceral-consignment \
  --env VISCERAL_API_KEY=vsk_your_key_here \
  -- uvx visceral-consignment-mcp

Then ask things like:

"Which consignors haven't had a completed payout since July?" "Summarize payout #918 — what sold and what did the consignor earn?" "How much did we pay out in total last month?"

Tools

Behavior notes

• Money values are decimal strings ("184.50") — the server instructs clients never to treat them as floats.
• On a short rate-limit (429 with Retry-After ≤ 15s) the server waits and retries once; longer waits surface as a readable error telling the model how long to pause.
• Versioned with the external API: these tools track v1 and follow the same early-access stability contract (see the External API v1 guide).

Development

Source lives in src/visceral_mcp/server.py — one @mcp.tool() per endpoint, a shared _get() helper for auth/errors/rate-limit handling.

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -q

Tests inject an httpx.MockTransport via server._transport and call the tool functions directly (the @mcp.tool() decorator returns the plain function) — no network, no real key needed.