venue-ops-mcp

An MCP server that gives Claude or any MCP client direct, read-only access to the daily trading figures of a multi-site restaurant group — and, more to the point, to the numbers where money leaves without anyone writing it down.

You: is anything leaking this week?

Claude: Eixample (BCN-01) — voided tickets have drifted from 1.55% of gross
to 4.60% over the last seven days, against a 28-day baseline. That is
799.16 EUR over the window. It is not a spike on one shift; it is a slope
across the whole week, which is the shape a till problem makes.

Why this exists

Most reporting tools answer the question everybody already asks: what did we sell? Sales are the easy number. They are on the till, on the dashboard, in the WhatsApp group by ten past midnight.

The numbers that decide whether a site makes money are discounts, comped items and voided tickets — the control block — and they almost never reach a daily report. A void rate sliding from 1% to 4% over three weeks does not look like anything on any given night. It looks like a bad Tuesday, then a quiet Thursday. It only looks like a problem when you compare a window against the window before it, which is what this server does.

The thresholds here are not copied from a statistics textbook. They come from having run venues.

Tools

Every tool is read-only, annotated as such, and takes response_format: "markdown" for a person or "json" for a program.

The two shapes of anomaly

venue_ops_find_anomalies compares the last 7 days against the 28 before them and reports two different things, because they mean different things:

• Drift — the whole recent window has moved. An unfixed rota, a till problem, a manager who has started comping to keep the peace. This is the expensive one and the one nobody spots.

• Spike — one day far outside the baseline. Usually a promotion nobody logged. Cheap to explain, worth confirming.

Findings under 40 EUR are dropped. They are real and they are not worth a phone call, and a report that cries wolf gets ignored by week three.

The data

data/operations.json is synthetic. Three venues, 182 days, generated by scripts/generate_data.py from a fixed seed so results are reproducible. It is not a real business and no real business is identifiable from it.

The numbers are invented; the shape is not. Weekday seasonality, the dine-in/delivery split, discount and void rates and labour percentage all sit inside the bands you see in casual dining.

Three anomalies are planted on purpose, so the detection has something real to find and so anyone can check that it works:

To point this at a real point-of-sale system, replace the loader in venue_ops_mcp/data.py. The tool layer does not care where rows come from.

Install

pip install -r requirements.txt
python scripts/generate_data.py

Use it with Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "venue-ops": {
      "command": "python",
      "args": ["-m", "venue_ops_mcp.server"],
      "cwd": "/absolute/path/to/venue-ops-mcp"
    }
  }
}

Restart Claude Desktop. Then ask it things like:

• Which venues do we have?

• How did Gran Via do last Saturday compared with the Saturdays before it?

• Check Barcelona for problems in the week ending 5 July.

• What did the group do in July?

Verify it

python scripts/smoke_test.py    # every tool, and the planted anomalies
python scripts/stdio_check.py   # the MCP handshake a real client performs

smoke_test.py asserts that the Barcelona drift is still detected and that a clean window produces no findings. A detector that fires on everything is worse than no detector, so both directions are tested.

Built with

Python 3.10+, the MCP Python SDK (MCPServer, stdio transport), Pydantic v2 for input validation. No external services, no credentials, no network calls — the server only reads a local file.

Licence

MIT.