VeloceMCP

Veloce MCP Server

A read-only Model Context Protocol (MCP) server that lets restaurant staff query their Veloce POS data in plain language through an MCP client — Claude Desktop, the MCP Inspector, Claude Code, etc.

Built with the FastMCP Python SDK. Every Veloce endpoint it touches is read-only — there are no tools that can change or delete data.

About this repository. This is a generalized, portfolio version of a server originally built for a multi-location restaurant client. Credentials, real location names, and all business data have been removed; the location names here (Downtown, Midtown, …) are placeholders you can rename. Veloce is a third-party POS platform and is not affiliated with this project.

What it can answer

| Tool | Answers questions like | |------|------------------------| | list_locations | "Which locations can I ask about?" | | get_sales_summary | "What were Downtown's total sales last Saturday?" | | get_daily_sales | "Show me Uptown day-by-day for last week." | | get_payment_breakdown | "How much came in via Uber vs cash at Midtown yesterday?" | | get_top_products | "What were Eastside's 10 best sellers in May?" | | get_category_sales | "Food vs beverage split at Westside last month?" | | get_hourly_sales | "What's the busiest hour at Downtown on Sundays?" | | get_service_mode_sales | "Dine-in vs delivery at Midtown last week?" | | get_employee_sales | "Who were the top servers at Uptown in April?" | | get_refunds_and_voids | "Any unusual refunds at Eastside yesterday?" |

Weekly reports

| Tool | Produces | |------|----------| | get_upsell_report | Per-server upsell performance: beverages + food upgrades + sides as a % of each server's sales. | | get_lto_report | Per-server Limited Time Offer sales vs. the tracked LTO list. | | get_avm_report | Average Meal Value (net sales ÷ meal count) with a daily breakdown. |

LTO items — managed as data, not code

The Limited Time Offer list lives in lto_items.json and is matched as case-insensitive substrings. When a promo changes, update it by conversation instead of combing the item list:

| Tool | Use | |------|-----| | get_lto_items / set_lto_items | View or replace the tracked LTO list. | | search_menu_items | Find sold items by keyword (e.g. every "blueberry" item). | | find_new_items | Surface items that started selling recently but weren't selling in an earlier baseline period — i.e. likely new LTOs. |

Typical flow: "What new items showed up this month at Downtown?" → find_new_items lists candidates → "Track those as LTOs" → set_lto_items saves them → get_lto_report uses them automatically.

It also exposes the location list as a resource (veloce://locations) and a daily_briefing prompt that produces an end-of-day manager summary.

Setup

1. Install dependencies (Python 3.10+):

   cd veloce-mcp-server
   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt

1. Configure your locations. Edit _LOCATION_KEYS in config.py to match your locations, then add credentials. Each location is a separate Veloce login, so each needs its own email/password.

   cp .env.example .env

Open .env and fill in the values. Never commit .env — only .env.example (which holds no secrets) is safe to share.

Test it locally with the MCP Inspector

mcp dev server.py

This opens the browser-based Inspector. Click Connect, then try a tool: pick get_sales_summary, enter a location (e.g. Downtown) and a date, and run it. This is the fastest way to confirm credentials and the connection work before wiring it into a client.

Connect it to Claude Desktop

Add this to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "veloce": {
      "command": "/absolute/path/to/veloce-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/veloce-mcp-server/server.py"]
    }
  }
}

Use absolute paths, then restart Claude Desktop. The Veloce tools will appear and you can ask questions like "What were Downtown's sales last Saturday and how did people pay?"

Notes & conventions

• Dates are YYYY-MM-DD. Where a range is optional it defaults to today.
• Tokens are cached in memory per location and refreshed automatically on a 401, so the server logs in once per location per session.
• Locations are matched case-insensitively and by prefix (down → Downtown).
• The server only loads locations that have both an email and password set, so it still runs with a subset configured.

Architecture

• server.py — defines the MCP tools, resource, and prompt (FastMCP).
• veloce_client.py — per-location auth, in-memory token caching, automatic re-auth on 401, and a generic authenticated GET helper. All calls are read-only.
• config.py — loads per-location credentials from the environment and resolves friendly location names.
• lto_items.json — the editable Limited Time Offer list.

Extending it

The Veloce API exposes many read-only endpoints; this server wraps the most useful ~10. To add another (e.g. /sales/taxes, /transactions/giftCards, /sales/discounts), add a new @mcp.tool() function in server.py that calls vc.api_get(location, "/the/path", {params}). See the Veloce API documentation for the full endpoint list.

License

MIT — see LICENSE.