MCP Server (AI Assistants)

MCP Server (AI Assistant Integration)

Connect your Lumabill account to AI assistants like Claude, ChatGPT, and Cursor using the Model Context Protocol (MCP). Once connected, your AI assistant can create invoices, look up clients, generate reports, and more — all through natural language.

The MCP server requires a Pro or Lifetime plan and an API key. Create one under Settings > API in the dashboard.

Prerequisites

1. Pro or Lifetime subscription — the MCP server uses the public API, which is a Pro feature
2. An API key — create one in Settings > API (read-only is fine for queries; read & write for full access)
3. A compatible AI client — Claude Desktop, Claude Code, Cursor, or any MCP-compatible tool

Setup

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "lumabill": {
      "type": "streamable-http",
      "url": "https://mcp.lumabill.ch/mcp?key=lmb_your_key_here"
    }
  }
}

File location:

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

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "lumabill": {
      "type": "streamable-http",
      "url": "https://mcp.lumabill.ch/mcp?key=lmb_your_key_here"
    }
  }
}

Cursor

1. Open Settings > MCP
2. Click Add MCP Server
3. Enter:
   • Name: lumabill
   • Type: streamable-http
   • URL: https://mcp.lumabill.ch/mcp?key=lmb_your_key_here

Replace lmb_your_key_here with your actual API key in all examples above.

Available Tools

Once connected, your AI assistant has access to all Lumabill API endpoints as tools, grouped by area:

Invoicing

• List, create, update, and delete invoices
• Create and manage offers/quotes
• Manage recurring invoices

Clients & Vendors

• Search and look up clients
• Create and update client records
• Manage vendor contacts

Expenses & Revenue

• Record and categorize expenses
• Track non-invoice income
• Query revenue data

Bookkeeping

• Create journal entries
• View the chart of accounts
• Manage fiscal years

Banking

• Import bank transactions (CAMT)
• Reconcile transactions

Reports

• Generate profit & loss statements
• Generate balance sheets
• Create VAT reports

Settings

• View profiles and company info
• Browse product catalog

Example Prompts

Once your AI assistant is connected, try prompts like:

• "Create an invoice for Muster AG for 3 hours of consulting at CHF 180/hour"
• "Show me all unpaid invoices"
• "What was my revenue last month?"
• "Generate a P&L report for Q1 2026"
• "Look up the client Meier GmbH"
• "Create an expense for CHF 49.90 for office supplies"
• "List all recurring invoices"

Permissions & Rate Limits

• Read-only API keys only expose read tools (list, get, reports). Write operations are hidden.
• Read & write keys expose all tools.
• Rate limits are the same as the REST API: 60 reads/minute and 20 writes/minute per key.
• The MCP server respects your key's profile scope — if the key is scoped to one profile, the assistant only sees that profile's data.

Troubleshooting

"Connection refused" or timeout

• Verify your API key is correct and starts with lmb_
• Check that the URL is exactly https://mcp.lumabill.ch/mcp?key=lmb_your_key_here (no trailing slash)
• Ensure your subscription is active (Pro or Lifetime)

"Unauthorized" or "Invalid API key"

• The key may have been revoked — check Settings > API in the dashboard
• Make sure you copied the full key including the lmb_ prefix

Tools not appearing

• Restart your AI client after editing the configuration
• For Claude Desktop, fully quit and reopen the application
• For Cursor, reload the window after adding the MCP server

"Read-only key" errors on write operations

• Your API key is set to read-only mode. Create a new read & write key if you need to create or modify data.

Rate limit errors (429)

• You are making too many requests. Wait a moment and try again.
• Consider batching operations or spreading them out over time.