venue-ops-mcp
An MCP server that gives read-only access to synthetic daily trading figures for a three-venue restaurant group, focused on finding where money leaks through discounts, comps, voids and labour.
List venues and data coverage (
venue_ops_list_venues) — discover venue ids, cities, seat counts and the date range every other tool accepts.Inspect a single trading day (
venue_ops_get_day) — sales by channel, covers, average ticket, the control block (discounts, comps, voids) and labour, with rates expressed against gross.Compare a day to the same weekday in prior weeks (
venue_ops_compare_weekday) — average the last 1–12 same-weekdays and show the variance, to judge whether a bad night is real.Total a date range (
venue_ops_period_summary) — aggregated figures and derived rates for one venue or the whole group plus a group total.Scan for control-block anomalies (
venue_ops_find_anomalies) — compares the last 7 days to the prior 28 and flags drift (sustained rise, e.g. till problems, rota issues) or spike (one outlier day), sorted by euros at stake, dropping findings under 40 EUR.Choose output format — every tool takes
response_format: "markdown"for people or"json"for programs.Safe by design — all tools are read-only, idempotent, non-destructive, non-open-world, and read only from a local file with no credentials or network calls.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@venue-ops-mcp is anything leaking this week?"
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.
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.
Related MCP server: FinOps AI Copilot MCP Server
Tools
Tool | What it answers |
| Which sites exist and what period the data covers |
| Everything about one day: sales by channel, covers, average ticket, control block, labour |
| Was this Saturday actually bad, or does it just feel bad? |
| Totals for a range, per venue and for the group |
| What is moving against its own baseline, in euros |
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:
Venue | What | When |
BCN-01 | Void rate drifts 0.9% → 5.2% and stops | 15 Jun – 5 Jul 2026 |
MAD-02 | Labour percentage blows out to 41% for one week | 6 – 12 Apr 2026 |
MAD-01 | Two isolated discount days at 14% | 9 May, 18 Jul 2026 |
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.pyUse 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 performssmoke_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.
GitHub Actions runs both checks on pushes and pull requests with Python 3.10 and 3.12. The badge above links to the public results.
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.
Available Tools
5 toolsvenue_ops_compare_weekdayARead-onlyIdempotent
Compare a day against the same weekday in previous weeks.
This is the only fair comparison in hospitality. Measuring a Monday against the Sunday before it makes every Monday look like a collapse and every Friday like a triumph; comparing like weekday with like weekday is what tells you whether something actually changed.
Args: params (CompareWeekdayInput): Validated parameters containing: - venue_id (str): Venue identifier - day (str): The day being judged, YYYY-MM-DD - weeks (int): How many previous same-weekdays to average, 1-12 (default 4) - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: The day, the same-weekday average, and the variance between them.
JSON schema:
{
"venue_id": str,
"day": {...}, # same shape as venue_ops_get_day
"comparison_days": [str], # dates averaged
"averages": {"net_sales": float, "covers": float,
"average_ticket": float, "labour_pct": float,
"discount_rate": float, "void_rate": float},
"variance": {...} # same keys, as fractions of 1
}Examples: - Use when: "Was last Saturday actually bad, or does it just feel bad?" - Don't use when: You want a whole month's totals (use venue_ops_period_summary).
Inputs: params (required). Returns: result
venue_ops_find_anomaliesARead-onlyIdempotent
Flag discounts, comps, voids or labour moving against their own baseline.
Compares the last 7 days against the 28 before them and reports two shapes. A drift is a sustained rise across the whole recent window, which is what a till problem or an unfixed rota looks like. A spike is one day far outside the baseline, usually a promotion nobody logged. Findings below 40 EUR are dropped: they are real but not worth a phone call.
Args: params (AnomalyInput): Validated parameters containing: - venue_id (Optional[str]): One venue, or omit to scan all - end (Optional[str]): Last day of the window, defaults to the dataset end - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: Findings sorted by money at stake, largest first.
JSON schema:
{
"window_end": str,
"findings": [
{
"type": "drift" | "spike",
"metric": str, # discount_rate | comp_rate | void_rate | labour_pct
"label": str, # human wording, e.g. "voided tickets"
"venue_id": str,
"baseline_rate": float, # fraction of 1
"euros_at_stake": float,
# drift only: window, baseline_window, recent_rate, relative_increase
# spike only: date, weekday, day_rate, z_score
}
]
}Examples: - Use when: "Is anything leaking this week?" - Use when: "Check Barcelona for problems ending 5 July." - Don't use when: You want the day's trading figures (use venue_ops_get_day).
Inputs: params (required). Returns: result
venue_ops_get_dayARead-onlyIdempotent
Return the full trading figures for one venue on one day.
Gives sales split by channel, covers, average ticket, the control block (discounts, comps, voids) and labour cost, with every rate expressed against gross so the percentages are comparable across venues.
Args: params (DayInput): Validated parameters containing: - venue_id (str): Venue identifier, e.g. 'MAD-01' - day (str): Trading day, YYYY-MM-DD - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: The day's figures.
JSON keys include: net_sales, dine_in_sales, delivery_sales, covers,
transactions, average_ticket, spend_per_cover, discounts, comps, voids,
control_total, gross_sales, discount_rate, comp_rate, void_rate,
labour_cost, labour_hours, labour_pct (float rates are fractions of 1).
Error response: "Error: <message>" naming the valid venues or dates.Examples: - Use when: "How did Gran Via do on 14 August?" - Don't use when: You want to know whether that day was normal (use venue_ops_compare_weekday).
Inputs: params (required). Returns: result
venue_ops_list_venuesARead-onlyIdempotent
List every venue in the dataset and the period the data covers.
Call this first when you do not know which venue ids exist. It is cheap and it tells you the date range every other tool will accept.
Args: params (ListVenuesInput): Validated parameters containing: - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: Venue list and covered period.
JSON schema:
{
"currency": str, # e.g. "EUR"
"period": {"start": str, "end": str},
"venues": [
{"venue_id": str, "name": str, "city": str, "seats": int}
]
}Examples: - Use when: "Which sites do we have data for?" - Don't use when: You already have a venue id and want figures (use venue_ops_get_day).
Inputs: params (required). Returns: result
venue_ops_period_summaryARead-onlyIdempotent
Total up a date range, for one venue or for the whole group.
Args: params (PeriodInput): Validated parameters containing: - start (str): First day, YYYY-MM-DD - end (str): Last day inclusive, YYYY-MM-DD - venue_id (Optional[str]): One venue, or omit for all venues plus a total - response_format (ResponseFormat): 'markdown' or 'json'
Returns: str: Totals and derived rates for the range.
JSON schema:
{
"period": {"start": str, "end": str},
"venues": {venue_id: {...aggregated figures...}},
"group_total": {...} # present only when venue_id was omitted
}Examples: - Use when: "What did the group do in July?" - Use when: "Give me Chamberi's numbers for the last two weeks." - Don't use when: You want a single day (use venue_ops_get_day).
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: listing venues, retrieving a single day, comparing to same weekday averages, aggregating a range, and detecting anomalies. There is no overlap or ambiguity between them, and cross-references in examples reinforce which tool to use for which question.
All five tools follow the exact same verb_noun pattern with the venue_ops_ prefix, using snake_case (find_anomalies, list_venues, get_day, compare_weekday, period_summary). The naming is perfectly predictable and consistent.
With 5 tools, the server is well-scoped for a venue operations analytics domain. Each tool earns its place and covers a distinct query pattern without being too thin or unnecessarily heavy.
The tool surface covers the core analytics needs: discovery (list), point-in-time snapshot (get day), fair comparison (compare weekday), aggregation (period summary), and proactive insight (find anomalies). No obvious gaps within the stated purpose of venue analytics.
Maintenance
Related MCP Connectors
Read-only restaurant finance, cost, stock and staff-hours assistant for restoorun owners.
Read-only tools for finding where a small business leaks deals, time, and cash.
Interrogez stock, recettes, CA, marge et frigos de votre restaurant (lecture seule).
Free for restaurant owners. Drop last night's close, get the one thing to fix before next shift.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server that enables restaurant staff to query Veloce POS data using natural language, supporting sales summaries, payment breakdowns, and weekly reports.MIT
- FlicenseBqualityDmaintenanceA secure, read-only MCP server that enables AI assistants to inspect transactions, vendor performance, wallet balances, and analytics through validated REST API calls.19-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to query live Toast POS data and generate sales, labor, and cash reports while answering restaurant operations questions, all in a read-only manner.-
- FlicenseNot gradedqualityCmaintenanceEnables read-only investigation of unusual crypto market activity by combining price, volume, volatility, order-book, and correlation signals into explainable anomaly reports and evidence timelines.-