Sales Analyzer MCP Server

A remote MCP server that exposes sales anomaly detection as tools Claude can call. It bundles a deterministic sample dataset — one year of daily sales for a fictional café, "Bean & Leaf" — and analyzes it with robust statistics (median absolute deviation), so anomalies like closures, pricing glitches, and structural product declines are detected in code, not guessed by the model.

The server returns only computed data: no LLM calls, no API keys, fully stateless. Built with the official MCP Python SDK (FastMCP) over the Streamable HTTP transport.

Tools

Tool	What it returns
list_weeks()	The 53 weeks in the dataset with date ranges, row counts, and completeness
analyze_week(week_number)	Weekly revenue, totals by product, week-over-week changes, top movers, daily series, and flagged anomalies with severity and reason
get_product_history(product_name)	A product's full weekly units/revenue series

Bad inputs (week 99, unknown product) return a clear {"error": ...} message instead of failing.

Project layout

• server.py — FastMCP server: transport, health check, and the three tools
• analytics.py — stdlib-only analytics: weekly aggregation + MAD-based anomaly detection
• generate_sample_data.py — seeded generator for the sample dataset (byte-identical every run)
• data/sales_2025.csv — the bundled dataset (regenerated at startup if missing)
• test_client.py — smoke test that exercises every tool against a running server

Run locally

pip install -r requirements.txt
python server.py

The server listens on port 8000 (override with the PORT env var):

• Landing page / health check: GET http://localhost:8000/ → an HTML page (HTTP 200)
• MCP endpoint: http://localhost:8000/mcp

Verify all tools in a second terminal:

python test_client.py

Deploy to Render (free tier)

1. Push this repo to GitHub.

2. In the Render dashboard, click New + → Blueprint and select the repo — render.yaml configures everything (Python web service, free plan, python server.py start command).

   • Or manually: New + → Web Service, build command pip install -r requirements.txt, start command python server.py.

3. Wait for the deploy to go live. Your MCP endpoint is:

   https://<your-service>.onrender.com/mcp
   

4. Sanity-check it: opening https://<your-service>.onrender.com/ in a browser shows the landing page (which also serves as the health check).

Note: free-tier services spin down after ~15 minutes of inactivity; the first request after that takes ~30-60 seconds while the instance cold-starts. The server is stateless, so this is harmless — retry once if a first call times out.

Add to Claude as a custom connector

1. In Claude (web or desktop), go to Settings → Connectors.

2. Click Add custom connector.

3. Enter the URL ending in /mcp, e.g. https://sales-analyzer-mcp.onrender.com/mcp, and add it. No authentication is required.

4. In a chat, enable the connector from the tools menu, then ask something like:

   Which weeks in the sales data look anomalous, and what happened in week 32?

Claude will call list_weeks, analyze_week, and get_product_history as needed and reason over the returned figures.

About the sample data

The dataset (6 products × 365 days of 2025) has realistic weekly rhythm, seasonality, and growth, plus four hidden anomalies the detectors rediscover:

• a 5-day closure in mid-March (pipe burst),
• a one-day viral spike in May,
• a week of 10x-inflated Latte revenue in August (decimal error — units normal),
• a permanent Blueberry Muffin collapse from October (supplier problem).

The generator is seeded, so the CSV is identical on every run.