Restaurant Ops MCP

Open-source MCP tools for analyzing restaurant menu economics with AI assistants.

Status: early alpha. The first release focuses on menu contribution margin and food-cost analysis from simple CSV data.

Maintained by a restaurant operator at Balboa Poke, with AI assistance for implementation. Restaurant experience shapes the problems; tests and documented calculations make the software inspectable. External adoption and business outcomes have not yet been established.

Why this exists

Restaurant operators often have useful data trapped in POS exports and spreadsheets, but turning that data into clear decisions usually requires manual analysis.

Restaurant Ops MCP exposes small, auditable tools that an MCP-compatible AI assistant can call to answer questions such as:

• Which menu items contribute the most after ingredient costs?

• What is the food-cost percentage for each item?

• Which items sell well but have weak contribution margins?

Price-change scenarios and period comparisons are planned, not implemented yet.

The project is intentionally starting small and transparent. Each calculation lives in ordinary Python so operators and contributors can inspect how the numbers are produced.

Related MCP server: mcp-csv-database

Current tools

calculate_menu_item_metrics

Calculates:

• food-cost percentage

• contribution margin per unit

• gross sales

• total ingredient cost

• total contribution margin

analyze_menu_csv

Accepts CSV text with these columns:

item,selling_price,ingredient_cost,units_sold

It returns a menu-level summary, item rankings by total contribution margin, and warnings for loss-making items or a period with no sales.

Synthetic example data is available in examples/menu.csv.

Review your week without an AI assistant

After installing, run:

restaurant-ops examples/menu.csv

The sample has sales of 8,152.50 across 615 units. The report shows theoretical ingredient cost, weighted food-cost percentage, and items ranked by contribution after ingredients. Amounts use the currency supplied in the CSV; do not mix currencies.

For machine-readable output:

restaurant-ops examples/menu.csv --json

See the weekly review guide for preparing your own data, interpreting results, and recording useful feedback. No AI account is needed for this local report.

Quick start

For a versioned source download, see GitHub releases. Extract the source archive, open its folder, and follow the virtual-environment and pip installation steps below (skip git clone when using an archive). This project is not published to PyPI; install from this repository or its releases.

Requirements

• Python 3.10+

• uv recommended, or any normal Python environment

• Node.js/npm only if you want the optional browser-based MCP Inspector

Using uv

git clone https://github.com/vgdikyan-droid/restaurant-ops-mcp.git
cd restaurant-ops-mcp
uv sync --extra dev
uv run restaurant-ops examples/menu.csv

For the optional MCP Inspector, run uv run mcp dev src/restaurant_ops_mcp/server.py.

Using pip

git clone https://github.com/vgdikyan-droid/restaurant-ops-mcp.git
cd restaurant-ops-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
restaurant-ops examples/menu.csv

On Windows, activate with .venv\Scripts\Activate.ps1 in PowerShell.

Connect an MCP client

This project uses the official MCP Python SDK v2 (mcp>=2.0,<3.0) and MCPServer. It is not the separate FastMCP package. See the official SDK documentation.

The installed restaurant-ops-mcp command runs the server over standard input/output (stdio). The client launches it when needed; it does not open a web port. Running it by itself waits quietly for protocol messages.

For clients that accept an mcpServers JSON configuration, use your installed environment's absolute executable path:

{
  "mcpServers": {
    "restaurant-ops": {
      "command": "/absolute/path/to/restaurant-ops-mcp/.venv/bin/restaurant-ops-mcp",
      "args": []
    }
  }
}

On Windows the executable is .venv\\Scripts\\restaurant-ops-mcp.exe. Configuration location varies by client. A client can also launch the virtual environment's Python with arguments -m restaurant_ops_mcp.server.

Try: “Use the restaurant tools to calculate a menu item with selling price 20, ingredient cost 6, and 10 units sold.” Expected total contribution: 140. The CSV tool accepts CSV text, not a filename, and does not read arbitrary files. If you use an AI client, CSV content and results may be sent to that client's provider. The standalone CSV report runs locally.

What these numbers mean

• Ingredient cost is the recipe cost per portion; units sold cover one period.

• Food-cost percentage = ingredient cost / selling price × 100.

• Weighted food-cost percentage = total ingredient cost / total sales × 100.

• Contribution = sales minus ingredients. It excludes labor, rent, payment and delivery fees, waste, and other costs, so it is not net profit.

• These are theoretical food costs, not actual inventory usage or purchase totals.

• Amounts are rounded to two decimal places for display; this is an operating estimate, not an accounting ledger.

• The JSON field gross_sales is price × units. Use realized prices after discounts and before tax/tips to approximate your POS sales consistently.

• With no units sold, the text report shows food cost as N/A. The JSON field weighted_food_cost_pct retains 0.0 for compatibility, alongside a warning.

Example CSV

item,selling_price,ingredient_cost,units_sold
Salmon Bowl,18.50,6.40,120
Chicken Bowl,15.00,4.10,180
Spicy Tuna Roll,13.50,4.70,95

Project principles

1. Useful before clever — tools should answer real operating questions.

2. Auditable math — calculations should be easy to inspect and test.

3. Portable data — start with CSV and simple schemas instead of locking users into one POS vendor.

4. AI as an interface, not the source of truth — the model can reason over results, but the underlying calculations stay deterministic.

Roadmap

• Menu-item margin calculator

• CSV menu analysis

• Automated tests

• Local CSV report for weekly reviews

• MCP connection test and CSV validation

• Compare periods (week vs. week / month vs. month)

• Ingredient price-change scenarios

• Menu engineering quadrants

• Inventory variance analysis

• POS-specific import adapters

• Example Claude Desktop / Claude Code configuration

Contributing

Contributions are welcome, especially from restaurant operators, hospitality technologists, and developers interested in practical MCP tooling.

See CONTRIBUTING.md.

To try a real workflow, follow the pilot checklist. Report a reproducible bug or operator feedback using the GitHub issue templates.

License

MIT