mcp-loyverse

A local-first, read-only MCP server for the Loyverse POS API that lets AI assistants query receipts, items, employees, customers, stores, and sales analytics — built for secure local use with Personal Access Tokens.

What & Why

mcp-loyverse bridges the Model Context Protocol (MCP) and the Loyverse POS API so that AI assistants like Claude can answer business questions about your point-of-sale data directly:

• "What were today's total sales?" — answered in a single tool call
• "Which was the best-selling item this week?" — aggregated automatically
• "Show me the top employees by sales this month" — with name resolution

Instead of the AI making dozens of paginated API calls, high-level analytics tools handle pagination, filtering, and aggregation internally, returning concise summaries that are token-efficient.

Features

• 15 MCP tools (1 system + 11 resource + 3 analytics)
• Automatic pagination for analytics — no manual cursor handling
• Date presets — today, yesterday, this_week, this_month, last_7_days, last_30_days
• Timezone-aware date resolution (configurable, defaults to UTC)
• Read-only — only GET requests, no data modification
• Secure — token never appears in logs or error messages
• Structured logging to stderr with configurable log level
• Retry logic — exponential backoff on 429 (rate limit), single retry on 5xx
• Safety limits — max 10,000 receipts per analytics query, 90-day max date range

Requirements

• Node.js 20+
• Loyverse account with a Personal Access Token (Settings > Personal Access Tokens)

Quick Start

No cloning or building required — just add the server to your MCP client:

Claude Code (CLI)

claude mcp add loyverse \
  -e LOYVERSE_API_TOKEN=your_personal_access_token_here \
  -e DEFAULT_TIMEZONE=America/Mexico_City \
  -- npx mcp-loyverse

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "loyverse": {
      "command": "npx",
      "args": ["mcp-loyverse"],
      "env": {
        "LOYVERSE_API_TOKEN": "your_personal_access_token_here",
        "DEFAULT_TIMEZONE": "America/Mexico_City"
      }
    }
  }
}

Other MCP clients

Any MCP-compatible client that supports stdio transport can connect. Use the command npx mcp-loyverse with the environment variables listed in Configuration.

Install from source

If you prefer to run from a local clone:

git clone https://github.com/novigante/mcp-loyverse.git
cd mcp-loyverse
npm install
npm run build

Then use node /path/to/mcp-loyverse/dist/index.js instead of npx mcp-loyverse in the examples above.

Verify

Ask your AI assistant: "Run the healthcheck tool" — it should return server status and configuration info.

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | LOYVERSE_API_TOKEN | Yes | — | Loyverse Personal Access Token | | LOYVERSE_BASE_URL | No | https://api.loyverse.com/v1.0 | API base URL | | DEFAULT_TIMEZONE | No | UTC | Timezone for date presets (e.g. America/Mexico_City) | | LOG_LEVEL | No | info | Log verbosity: debug, info, warn, error | | MCP_READ_ONLY | No | true | Read-only mode (always true in v0.1) |

Available Tools

System

| Tool | Description | |------|-------------| | healthcheck | Server status, version, and configuration check |

Resource (CRUD read-only)

| Tool | Description | Key Inputs | |------|-------------|------------| | list_receipts | Search receipts by date, store, or receipt numbers | period, from/to, store_id, receipt_numbers | | get_receipt | Get full receipt details | receipt_number | | list_items | List catalog items | items_ids, limit, cursor | | get_item | Get item details by ID | item_id | | list_employees | List employees (staff, waiters, cashiers) | employee_ids, limit, cursor | | get_employee | Get employee details by ID | employee_id | | list_customers | List customers, optionally filter by email | customer_ids, email, limit, cursor | | get_customer | Get customer details by ID | customer_id | | list_stores | List all stores | store_ids, show_deleted | | get_store | Get store details by ID | store_id | | get_merchant | Get merchant profile and currency settings | (none) |

Analytics (high-level, auto-paginated)

| Tool | Description | Key Inputs | |------|-------------|------------| | sales_summary | Revenue, receipt count, average ticket, taxes, tips | period, from/to, store_id | | top_selling_items | Top items ranked by quantity or sales amount | period, metric, limit | | top_employees_by_sales | Top employees by sales or receipt count (resolves names) | period, metric, limit |

Example Prompts

• "What were today's total sales?"
• "Show me the top 5 best-selling items this week"
• "Which employee had the highest sales this month?"
• "List all receipts from yesterday"
• "Get the details of receipt number R-1234"
• "What was the average ticket amount this week?"
• "What currency does the merchant use?"

Architecture

src/
  config/         Configuration (env validation, secrets, logger)
  loyverse/       HTTP client, API error handling, resource clients
  domain/         Analytics: pure aggregation functions, receipt collector
  tools/          MCP tool definitions and handlers
    _shared/      Date range helpers, pagination, result builders
  mcp/            MCP server setup and tool registry
  index.ts        Entry point (stdio transport)

Each tool exports { definition, handler }. The toolRegistry.ts wires definitions into the MCP server. Analytics tools compose the receipt collector (auto-pagination) with pure aggregation functions.

Security

• Read-only — only HTTP GET requests to the Loyverse API
• Token protection — the API token never appears in logs, error messages, or tool responses
• Secret redaction — structured log data is automatically sanitized
• Local-first — runs on your machine via stdio transport; no external server or network exposure

Limitations (v0.1)

• Read-only — no creating, updating, or deleting resources
• PAT only — no OAuth flow; requires a Personal Access Token
• stdio only — no HTTP/SSE transport (designed for local MCP clients)
• No caching — every tool call fetches fresh data from the API
• Analytics limit — max 10,000 receipts per query; max 90-day date range

Roadmap

• [x] Publish to npm (npx mcp-loyverse)
• [ ] Write tools (create/update items, customers)
• [ ] OAuth 2.0 authentication flow
• [ ] HTTP/SSE transport for remote deployment
• [ ] Response caching with TTL
• [ ] Webhook support for real-time updates
• [ ] Inventory and stock level tools

Testing

Unit tests

npm test                   # 194 tests (Vitest)
npm run test:watch         # Watch mode
npx vitest run tests/tools/salesSummary.test.ts  # Single file

Integration tests

End-to-end tests that exercise all 15 tools against the live Loyverse API via the MCP protocol (stdio transport). Validates connectivity, resource reads, analytics, cross-data consistency, error handling, and pagination.

Prerequisites: a .env file with a valid LOYVERSE_API_TOKEN.

cp .env.example .env
# Edit .env — set your real LOYVERSE_API_TOKEN
npm run build
node tests/integration/run-integration.mjs

The script connects as an MCP client, runs 40 tests across 6 phases, and writes raw results to tests/integration/results.json.

| Phase | Tests | What it validates | |-------|-------|-------------------| | 1. Connectivity | 2 | Healthcheck, merchant auth | | 2. Resources | 13 | List/get for all 6 entities, filters | | 3. Analytics | 7 | Sales summary, top items, top employees | | 4. Cross-validation | 5 | Data consistency between tools | | 5. Error handling | 9 | Invalid IDs, missing params, server stability | | 6. Pagination | 4 | Cursor-based pagination per resource |

See docs/integration-test-plan.md for detailed validation criteria.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Write tests first (TDD) — npm test
4. Implement your changes
5. Run integration tests locally (requires your own LOYVERSE_API_TOKEN)
6. Verify: npm run build && npm test && npm run lint
7. Submit a pull request — CI must pass before merge

Releasing

Releases are published to npm automatically via GitHub Actions. Only repository maintainers can create releases.

1. Merge all desired changes to main via PR
2. Update the version in package.json (npm version patch|minor|major) and merge via PR
3. Create a GitHub Release with tag vX.Y.Z matching package.json
4. The workflow builds, tests, and publishes to npm with provenance

License

Apache-2.0