How do I use KiezelPay Sales MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@KiezelPay Sales MCP What's my sales summary for today?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

KiezelPay Sales MCP

by skusVV

Overview Schema Related Servers Score Discussions

Python

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.

Related MCP server: Amazon Ads Manager MCP Server

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()).

Available Tools

6 tools

get_product_salesA

Get aggregated sales for a single product derived from purchase history: purchase count, first/last sale, and breakdowns by country, platform, and trigger. Includes revenue if the history records carry a price.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	How many recent purchases to scan when aggregating this product.
`product`	Yes	Exact product name (see list_products).

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It discloses that revenue is included only conditionally ('if the history records carry a price'), which is a meaningful behavioral nuance. It also implies the tool aggregates from purchase history rather than direct sales data. It does not cover edge cases like empty history or limit-based truncation, but the core behavior is well conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly written sentence that front-loads the purpose and lists concrete output components. Every phrase adds information, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is sufficiently complete for a simple aggregation tool without an output schema. It covers the main return values and the conditional revenue behavior. Minor gaps remain around limit behavior and edge cases like no matching history, but these are not critical for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (product and limit) are already described in the schema. The description adds no extra semantic detail beyond what the schema provides, such as the fact that limit controls how many purchases are scanned. This meets the baseline for full schema coverage but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb ('Get') and clearly identifies the resource ('aggregated sales for a single product'). It enumerates the exact outputs (purchase count, first/last sale, breakdowns by country, platform, trigger) and distinguishes this tool from generic sales summaries or raw purchase history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by emphasizing 'single product' and 'derived from purchase history,' which differentiates it from broader summary tools. However, it does not explicitly state when to prefer this tool over get_sales_summary or get_purchase_history, nor does it mention alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_purchase_historyA

Get recent individual purchases. Each record includes paidDate, product, productId, country, platform, device, gross totalAmount, net amountToPayOut, status, and isRefunded. Use for detailed, purchase-level questions.

ParametersJSON Schema

Name	Required	Description	Default
`sort`	No	Sort by date: 'desc' (newest first) or 'asc'.	desc
`limit`	No	Max number of recent purchases to return (1-500).
`platform`	No	Optional platform filter: 'fitbit' or 'garmin'. Omit for all platforms.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It lists all fields returned per record (paidDate, product, productId, country, platform, device, gross, net, status, isRefunded), which is valuable beyond the input schema. The read-only nature is implied by 'Get' and no side effects are mentioned, but the return-field disclosure compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core action, and every phrase adds value. The first sentence states what it does, the second lists output fields and gives usage guidance. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description compensates by enumerating the returned fields. It also provides usage context. However, it does not mention pagination or the constraint that recent is bounded by the limit parameter, though that is in the schema. Overall, it is adequately complete for a read-only list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage for all parameters (sort, limit, platform) with descriptions. The description does not add any semantics beyond what the schema says (e.g., 'recent' aligns with sort/limit defaults). Baseline 3 is appropriate because the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'Get recent individual purchases' with a specific verb and resource, and clarifies it returns granular purchase-level data. It distinguishes itself from sibling summary tools like get_sales_summary and get_product_sales by stating 'Use for detailed, purchase-level questions.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: 'Use for detailed, purchase-level questions.' It implies not to use it for summary/aggregate questions but does not explicitly name alternative tools or state when not to use it, so it misses a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sales_summaryA

Get the KiezelPay account sales summary: current balance, total purchases, total income, active trials, total paid out, and next/previous payout details.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It thoroughly discloses the return contents (current balance, total purchases, income, active trials, paid out, payout details), which is the key behavior. It does not explicitly state read-only or side effects, but the verb 'Get' implies a safe read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that names the resource and enumerates all the aggregated data points without redundant words or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema), the description is complete. It lists all the data points returned, leaving no ambiguity about the tool's scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. The description need not provide any parameter details, and the baseline of 4 for zero-parameter tools applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('KiezelPay account sales summary') and enumerates the key metrics (balance, purchases, income, trials, payouts). This clearly distinguishes it from sibling tools like get_sales_today and get_sales_yesterday which focus on specific periods.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies the tool is for an overall account summary, which provides clear context. However, it does not explicitly state when to use this over sibling tools like get_sales_today or get_sales_yesterday, nor does it mention exclusions. This is close to 'clear context, no exclusions'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sales_todayA

Get today's sales: your number of purchases, revenue (amount), and your rank among KiezelPay merchants for the day. Uses the local timezone for the day boundary.

ParametersJSON Schema

Name	Required	Description	Default
`platform`	No	Optional platform filter: 'fitbit' or 'garmin'. Omit for all platforms.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It adds a valuable behavioral detail about using the local timezone for the day boundary and clarifies that the output includes a merchant rank, which is not obvious from the name alone. It does not disclose rate limits or side effects, but as a read-only 'get' operation, that is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences effectively front-load the main purpose and then add a relevant timezone note. There is no redundant or filler content, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description adequately explains what the tool does, what it returns, and the relevant timezone behavior. It is complete enough for an agent to understand the tool's function and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides a complete description for the platform parameter, including valid values ('fitbit' or 'garmin') and behavior when omitted. The tool description adds no additional parameter semantics beyond what the schema states, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves today's sales, specifying the metrics returned (number of purchases, revenue amount, rank). It distinguishes from siblings like get_sales_yesterday by explicitly scoping to today and noting the local timezone boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context that this tool is for today's sales and uses the local timezone. While it doesn't explicitly name alternatives or exclusions, the 'today' scope and sibling names like get_sales_yesterday make the usage context clear without needing further guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sales_yesterdayA

Get yesterday's sales: your number of purchases, revenue (amount), and your rank among KiezelPay merchants for the day. Uses the local timezone for the day boundary.

ParametersJSON Schema

Name	Required	Description	Default
`platform`	No	Optional platform filter: 'fitbit' or 'garmin'. Omit for all platforms.

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the return fields (purchases, revenue, rank) and the timezone behavior, which is valuable context. It does not discuss side effects or auth, but for a read-only sales query this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences cover all essential information without padding. The first sentence lists the outputs, and the second clarifies the timezone detail—no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only query with one optional parameter and no output schema, the description is complete: it names every returned field and the timezone nuance. There is no missing behavior that the agent needs to know.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema fully describes the only parameter (platform) with allowed values and default. The description adds no extra parameter semantics beyond what the schema provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifically identifies the resource (yesterday's sales), the verb (get), and the exact outputs (purchases, revenue, rank). It clearly distinguishes from siblings like get_sales_today by the explicit 'yesterday' scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by specifying the time period (yesterday) and timezone boundary, making it obvious when to use this tool. However, it does not explicitly mention alternatives or exclusions relative to sibling tools like get_sales_summary or get_sales_today.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_productsA

List the distinct product names sold recently, derived from purchase history. Use this to discover which products exist before analyzing one.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	How many recent purchases to scan when deriving the product list.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that output is derived from purchase history and is deduplicated ('distinct'), which is useful behavioral context. It lacks details such as ordering, time window, or that 'limit' controls scans rather than results, which is only covered in the schema. Without annotations, the description carries a moderate burden but is not fully transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no filler, front-loading the action and purpose. It is appropriately concise and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is straightforward, and the description covers functionality and intended use. However, it omits return format and the meaning of 'recently,' and with no output schema or annotations, the agent gains limited context beyond basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'limit' is fully described in the schema with a clear explanation ('How many recent purchases to scan'), providing 100% coverage. The tool description adds no additional parameter-specific semantics, only reinforcing the data source, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('List the distinct product names sold recently') and clarifies its purpose ('discover which products exist before analyzing one'). This distinguishes it from sibling tools like get_product_sales that focus on metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs when to use it ('Use this to discover which products exist before analyzing one'), giving clear context for tool selection. However, it does not explicitly name alternatives or exclusion criteria, falling just short of full guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool targets a distinct aspect of sales data: products, account summary, daily stats, raw purchases, and product-level aggregates. The only close pair, get_sales_today and get_sales_yesterday, are clearly separated by the day in their names and descriptions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern (list_products, get_sales_summary, get_sales_today, get_sales_yesterday, get_purchase_history, get_product_sales). The mix of 'list' and 'get' is standard and predictable, with no camelCase or chaotic variations.

Tool Count5/5

Six tools is well-scoped for a sales-focused MCP server. Each tool covers a distinct need without redundancy, making the set feel intentional and manageable.

Completeness4/5

The tool surface covers the core sales questions: summary, daily performance, raw history, product listing, and per-product breakdowns. Minor gaps exist, such as no arbitrary date-range sales tool or explicit trial/refund analytics, but these can be worked around via purchase history and product sales.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
mcpOAuth
com.gibsonai
GibsonAI MCP server: manage your databases with natural language
Databases Search
233
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748

Related MCP Servers

nl2sql-mcp
Databases RAG Systems Search
bradsjm
F
license
Not graded
quality
F
maintenance
A production-ready MCP server that transforms natural language into safe, executable SQL queries with multi-database support and intelligent schema analysis.
Updated a year ago (2025-09-26 15:50 UTC)
1
Amazon Ads Manager MCP Server
Marketing Databases
amekala
A
license
Not graded
quality
D
maintenance
MCP server for managing and analyzing Amazon Advertising data through natural language queries.
Updated a year ago (2025-03-16 23:47 UTC)
22
7
MIT
VeloceMCP
Finance E-commerce & Retail
hassan3301
A
license
Not graded
quality
C
maintenance
A read-only MCP server that enables restaurant staff to query Veloce POS data using natural language, supporting sales summaries, payment breakdowns, and weekly reports.
Updated 2 months ago (2026-06-24 02:30 UTC)
MIT
agente-ecommerce-mcp-memoria
AbelCierto
F
license
Not graded
quality
B
maintenance
An MCP server that exposes a LangChain agent with short-term memory to analyze real e-commerce data through predefined SQL tools, enabling natural language queries on sales, customers, and logistics.
Updated 2 months ago (2026-07-19 01:03 UTC)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/skusVV/KiezelPay-Sales-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server