loyverse-sdk 0.4.3

Asynchronous Python SDK for the Loyverse API

Loyverse SDK

Asynchronous Python SDK, CLI, and MCP server for the Loyverse API — a point-of-sale (POS) platform for managing sales, inventory, and customers.

Features

• Async/await client built on httpx for non-blocking API calls
• Type-safe request/response models powered by Pydantic
• Automatic pagination with cursor-based iter_all() iteration
• Full CRUD across 16 endpoints
• loyverse CLI — list, create, update, delete, export, and analyze from the terminal
• loyverse-mcp server — 18 read-only tools exposing your POS data to LLM clients (Claude Desktop, etc.)
• DuckDB export — a local relational warehouse for SQL analytics
• Flat-file export — write any query straight to CSV or Parquet
• Analytics engine — revenue, products, customers, profitability, inventory, and more

Install

uv add loyverse_sdk          # core SDK
uv add "loyverse_sdk[mcp]"   # with the MCP server

See Installation for pip, GitHub, and extras.

Quickstart

import asyncio
from loyverse_sdk import LoyverseClient

async def main():
    client = LoyverseClient()                 # reads your token from ~/.loyverse
    response = await client.customers.list()
    print(f"Found {len(response.items)} customers")
    await client.close()

asyncio.run(main())

Run loyverse init once to store your API token. See Configuration and Quickstart to get going.

Documentation

Full documentation lives in the docs/ wiki — start at Home. Highlights:

• Getting started: Installation · Configuration · Quickstart
• Python SDK: Client · Endpoints · Query Models · Models · Helpers · Error Handling
• Export & analytics: DuckDB Export · Flat-File Export · Analytics
• Tools: CLI · MCP Server
• Project: Development

The pages under docs/ use [[wikilink]] syntax so they render as a connected GitHub Wiki. When browsing them in the repo, use the relative links above.

License

MIT — see LICENSE.