KiezelPay Sales MCP

An MCP client + server that lets you talk to your KiezelPay merchant sales data in natural language. Claude picks which reporting call to make, your products become attachable context, and common analyses are one-word commands.

The read-only KiezelPay merchant reporting API is wrapped as:

• Tools (Claude calls these autonomously)
  • get_sales_summary - balance, totals, active trials, next/previous payout
  • get_sales_today / get_sales_yesterday - your sales vs. the best merchant + your rank (optional platform)
  • get_purchase_history - recent individual purchases (limit, platform, sort)
  • list_products - distinct product names, derived from history
  • get_product_sales - aggregated stats for one product
• Resources - your products (derived by aggregating the product field across purchase history)
  • kpay://products - list of product names
  • kpay://products/{product} - one product's aggregate (count, revenue*, countries, platforms, first/last sale)
• Prompts - one-word analyses
  • /analyze-product <product> - performance deep-dive
  • /trend-product <product> - trajectory over the available history window
  • /predict-product <product> - near-term estimate (a heuristic extrapolation, not a statistical forecast)
  • /sales-report - overall executive summary

* revenue is included only if the history records carry a price field.

Prerequisites

• Python 3.10+
• An Anthropic API key (for the chat host)
• A KiezelPay merchant API key - get it at https://kiezelpay.com/account/api
  • The public test key 0123456789abcdef0123456789abcdef works for summary/today/yesterday, but not /history, so products and the product prompts need a real key.

Setup

1. Configure environment variables

Copy .env.example to .env and fill in the values:

ANTHROPIC_API_KEY=""          # your Anthropic API key
CLAUDE_MODEL="claude-sonnet-5"
KIEZELPAY_API_KEY=""          # your KiezelPay merchant key
USE_UV="1"

The KiezelPay key is used only by the MCP server, is read from the environment, and is never returned to the model or printed. .env is gitignored.

2. Install dependencies

Using uv (recommended):

uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e .

Or without uv:

python -m venv .venv
source .venv/bin/activate
pip install anthropic python-dotenv prompt-toolkit "mcp[cli]>=1.8.0" "httpx>=0.27.0"

3. Run the chat host

uv run main.py     # or: python main.py

Usage

Chat naturally - Claude will call the right tools:

> How did sales go today, and what's my current balance?
> Which products sold the most in the last 200 purchases?

Attach a product as context with @ (Tab to autocomplete):

> How is @RadPro doing lately?

Run an analysis prompt with / (Tab to autocomplete):

> /analyze-product RadPro
> /trend-product RadPro
> /predict-product RadPro
> /sales-report

Use from Claude Desktop / Claude Code

The server speaks stdio, so any MCP host can run it. Example Claude Desktop entry:

{
  "mcpServers": {
    "kiezelpay": {
      "command": "uv",
      "args": ["run", "mcp_server.py"],
      "cwd": "/absolute/path/to/kiezelpay-mcp",
      "env": { "KIEZELPAY_API_KEY": "your_key_here" }
    }
  }
}

Project layout

File	Role
mcp_server.py	KiezelPay Sales MCP server (tools, product resources, prompts)
kpay_api.py	Thin async HTTP client for the KiezelPay merchant API + product aggregation
mcp_client.py	Generic MCP client + a small test harness (uv run mcp_client.py)
main.py	CLI chat host entry point
core/	Chat host internals (Claude wrapper, chat loop, tool manager, CLI I/O)

Notes & caveats

• The API is read-only; this MCP never mutates anything.
• Products are derived from history, so the catalog only reflects the fetched window (CATALOG_LIMIT in mcp_server.py, default 200). Raise it for a longer catalog.
• /predict-product is a reasoning-based estimate over past patterns, not a real forecast.
• If today/yesterday day boundaries look off, adjust the timezone offset in kpay_api.py (tz_offset_minutes()).