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

Weekly reports

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:

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.

Related MCP server: MCP PostgreSQL

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.