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: @filippofilip95, Digitaliko

---

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
• Field Filtering - Extract specific fields as tabular data (array of arrays) for easy processing
• 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:

python server.py

Test with MCP Inspector:

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, see LICENSE.

Contributing

Contributions welcome. Submit issues or pull requests for improvements.

About

Built and maintained by Digitaliko. How we design MCP servers like this one: How to build an MCP server.