Sales Agent MCP

Ask your shop's data questions in plain language — through any AI assistant, safely.

A Model Context Protocol server that gives AI assistants (Claude Desktop, Claude Code, Cursor and any other MCP client) read-only tools over a retail shop's sales, stock, margins and customer credit, plus a small, transparent agent that answers questions with those tools — using Anthropic models or any OpenAI-compatible model, including local ones through Ollama.

"What has run out?" · "Am I selling anything at a loss?" · "Who owes me the most, and since when?" · "Draft a payment reminder in Hausa for Zainab." · "Compare this week with last week."

Why this project

Most small shops in Nigeria already record every sale in a POS app, but the owner still can't simply ask the data a question. Agents built on MCP can do that — if they are safe. This project focuses on the parts that make an agent trustworthy enough to point at real business data:

Related MCP server: db-mcp

The tools

The server also exposes the database schema as a resource (shop://schema) and a ready-made Weekly business review prompt.

Quick start

git clone https://github.com/Elscorpio96/sales-agent-mcp && cd sales-agent-mcp
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .

sales-agent seed                    # creates data/shop.db: 120 days of generated sales for a fictional shop
sales-agent tools                   # list the tools
sales-agent call low_stock          # call a tool directly — no model, no API key
sales-agent call top_products --args '{"period": "this_month", "by": "profit", "limit": 5}'

Use it from Claude Desktop (or any MCP client)

sales-agent config                  # prints the block below with the right paths for your machine

{
  "mcpServers": {
    "sales-agent": {
      "command": "/path/to/sales-agent-mcp/.venv/bin/python",
      "args": ["-m", "sales_agent.server", "--db", "/path/to/sales-agent-mcp/data/shop.db", "--log-level", "WARNING"]
    }
  }
}

Paste it into Claude Desktop's claude_desktop_config.json, restart, and ask about the shop. For remote clients, run sales-agent-server --http --port 8000 to serve MCP over Streamable HTTP (bound to 127.0.0.1 by default).

Use the bundled agent

export ANTHROPIC_API_KEY=...        # or use a local model, below
sales-agent ask "What needs my attention this week?"

# Any OpenAI-compatible model, e.g. a local one with Ollama:
sales-agent ask "Who owes me the most?" --provider openai --model llama3.1 --base-url http://localhost:11434/v1

# Full trace (every tool call, arguments, timings, tokens) as JSON, plus an audit log:
sales-agent ask "Am I losing money on anything?" --json --audit-log audit.jsonl

How it works

flowchart LR
    U[Shop owner] -->|question| A[Agent loop<br/>sales_agent.agent]
    C[Claude Desktop / Cursor / any MCP client] -->|MCP stdio or HTTP| S
    A -->|MCP: list_tools / call_tool| S[MCP server<br/>sales_agent.server]
    A <-->|tool use| M[(Model<br/>Anthropic or OpenAI-compatible)]
    S --> Q[Validated queries<br/>sales_agent.queries]
    Q -->|read-only| D[(SQLite<br/>sales, stock, credit)]
    S -.-> L[Audit log JSONL]

The agent is deliberately framework-free (about 250 lines) so every step is visible: it lists the server's tools, sends them to the model, executes the tool calls the model asks for through MCP, returns the results, and stops at a final answer or a step budget. Long tool results are truncated, tool errors are passed back so the model can correct itself, and the full trace is available as JSON.

Demo data

sales-agent seed generates 120 days of trading (4,700 sales, 10,400 line items) for Mai Kanti Mini Mart, a fictional shop in Bauchi, with 36 everyday products in naira, three cashiers, twelve credit customers and repayments. It is shaped to contain things worth finding — busier Fridays and month ends, two items out of stock, a supplier price rise that left 5L groundnut oil selling below cost, and two customers over their credit limit who have never paid back. All of it is generated; none of it describes a real business or real people. Point --db at your own SQLite file with the same schema (sales-agent call + shop://schema show it) to use real data.

Testing and evaluation

pip install -e ".[dev]"
pytest -q                     # 57 tests
ruff check . && mypy sales_agent   # mypy in strict mode

• Query correctness: every reported figure (revenue, profit, credit sales, group breakdowns, rankings, stock cover, losses, balances) is recomputed from the raw rows in plain Python and compared.

• Safety: writes are rejected by the database; bad periods, oversized limits and malformed arguments are refused; phone numbers are masked; reminders are never sent.

• MCP: tool listing, schemas and annotations, structured results, error mapping, audit log, resource and prompt — in-process and over a real stdio subprocess, the transport Claude Desktop uses.

• Agent: the tool loop, step limit, truncation, unknown tools and invalid JSON, and the exact Anthropic and OpenAI request/response formats (HTTP mocked).

• Live evals: evals/evalsentry.yaml asks the real agent nine golden questions — tool choice, exact figures, a Hausa reminder, refusing to edit data, refusing to invent numbers for dates outside the data, and an off-topic question — graded by rules and an LLM judge, each run twice. CI runs it whenever an ANTHROPIC_API_KEY repository secret is set; tests/test_golden_facts.py keeps the expected facts in sync with the data.

CI runs on Python 3.11–3.13 (Linux) and 3.12 (Windows), plus a CLI smoke test over stdio.

Status and limitations

• The agent's tests use simulated model responses in the providers' documented formats; no live model run is claimed here. Add an API key (or a local Ollama model) and run the eval suite to measure a specific model.

• Built and tested against the MCP Python SDK v2 (MCPServer). It speaks the standard protocol over stdio and Streamable HTTP, but I have not tested every MCP client.

• Single shop, single SQLite database, read-only. Multi-shop data, authentication for the HTTP transport and write actions with human approval are on the roadmap.

Roadmap

• Connector for the Ilelah Business Suite cloud database (Postgres/Supabase) behind the same tools

• OAuth for the HTTP transport; per-user tool permissions

• Human-approved actions (e.g. send a reminder via WhatsApp after the owner confirms)

• Forecasting tool (demand for the next 2 weeks) and anomaly alerts

Licence

MIT © 2026 Walid Bello Yakubu