SuperFaktura MCP Server

SuperFaktura MCP Server

Model Context Protocol (MCP) server for SuperFaktura invoicing system. Enables AI assistants to interact with SuperFaktura API for managing invoices, clients, and expenses.

Author: @fillippofilip95

---

Features

• Invoice Management - Create, list, edit, delete, send invoices with 40+ parameters
• Client Management - Full CRUD operations with 30+ fields
• Expense Management - Complete expense tracking with file attachments
• Advanced Filtering - 25+ filter options for invoices, comprehensive search across all resources
• Multi-tenant Support - Deploy as public MCP server or run locally

---

Quick Start

1. Install

git clone https://github.com/digitaliko/superfaktura-mcp.git
cd superfaktura-mcp
pip install -r requirements.txt

2. Get API Credentials

1. Log in to SuperFaktura
2. Go to Tools → API
3. Copy your API key

3. Configure Claude Desktop

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

{
  "mcpServers": {
    "superfaktura": {
      "command": "python3",
      "args": ["/absolute/path/to/superfaktura-mcp/server.py"],
      "env": {
        "SUPERFAKTURA_EMAIL": "your-email@example.com",
        "SUPERFAKTURA_API_KEY": "your-api-key-here",
        "SUPERFAKTURA_COUNTRY": "sk"
      }
    }
  }
}

Restart Claude Desktop after configuration.

---

Usage Examples

Create an invoice: ``` Create an invoice for client ID 123 with items:

• Web design (€500)
• Hosting (€50/month)

**List unpaid invoices:**

Show me all unpaid invoices from last month with amounts over €1000 ```

Add a client: `` Add a new client: ACME Corp, email: billing@acme.com, IČO: 12345678 ``

Track an expense: `` Record an expense: Office supplies €150 from yesterday ``

---

Documentation

• API Reference - Complete list of all tools and parameters
• Deployment Guide - Local and public MCP server deployment options

---

Available Tools

Invoices (9 tools)

create_invoice, list_invoices, get_invoice, edit_invoice, delete_invoice, send_invoice, mark_invoice_paid, get_invoice_pdf, set_invoice_language

Clients (5 tools)

create_client, list_clients, get_client, update_client, delete_client

Expenses (5 tools)

create_expense, list_expenses, get_expense, edit_expense, delete_expense

See API Reference for detailed documentation.

---

Country Support

| Country | Code | URL | |---------|------|-----| | Slovakia | sk | moja.superfaktura.sk | | Czech Republic | cz | moje.superfaktura.cz | | Austria | at | meine.superfaktura.at | | Sandbox (SK) | sandbox-sk | sandbox.superfaktura.sk | | Sandbox (CZ) | sandbox-cz | sandbox.superfaktura.cz |

---

Development

Run server: ``bash python server.py ``

Test with MCP Inspector: ``bash npx @modelcontextprotocol/inspector python server.py ``

---

References

Implementation based on:

• SuperFaktura Official API Client
• SuperFaktura REST API Docs
• OpenAPI Specification by @xseman

---

License

Apache-2.0

Contributing

Contributions welcome. Submit issues or pull requests for improvements.