VeloceMCP

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
   

2. 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.