Fakturia API MCP

An unofficial MCP (Model Context Protocol) server that provides full access to the Fakturia billing and subscription management API. Connect your AI assistant to Fakturia and manage customers, contracts, invoices, subscriptions, and more through natural language.

Disclaimer: This is an unofficial, community-built project. It is not affiliated with, endorsed by, or supported by Luminea IT Services GmbH, the company behind Fakturia. "Fakturia" is a product of Luminea IT Services GmbH. The included OpenAPI spec in docs/api/ was obtained from Fakturia's public API documentation endpoint.

What is this?

This MCP server wraps the entire Fakturia REST API and exposes every endpoint as an MCP tool. This means any MCP-compatible AI client (such as Claude Code, Claude Desktop, or other MCP clients) can interact with your Fakturia account directly — creating customers, managing subscriptions, generating invoices, pulling reports, and more.

Available Tools

123 tools across 14 API domains:

| Domain | Tools | Examples | |--------|-------|---------| | Customers | 14 | Create, update, search customers; manage SEPA mandates and custom fields | | Contracts | 32 | Full lifecycle: create, activate, terminate, upgrade; manage discounts, attachments, commission rules | | Invoices | 10 | List, retrieve, pay, cancel, reopen, rebill invoices; download PDFs | | Subscriptions | 9 | Manage subscription items, custom prices, price calculations | | Items | 9 | CRUD for billable items/products; manage prices and categories | | Orders | 7 | Process signup page orders; create customers/contracts from orders | | Accounts | 7 | Manage billing accounts, transactions, and customer assignments | | Reports | 7 | Generate customer, contract, invoice, and MRR reports; download exports | | Credit Notes | 6 | Retrieve credit notes and corrections; download PDFs | | Discounts/Coupons | 6 | Create discount/coupon configurations; validate and redeem coupon codes | | User Logins | 6 | Manage customer center logins: create, activate, lock, password reset, SSO tokens | | Activities | 4 | Track billable activities on contracts | | Webhooks | 4 | Configure and manage webhook notifications | | Projects | 2 | List projects and their contracts |

All tools include comprehensive descriptions and parameter documentation, making them easy to discover and use from any MCP client.

Quick Start

Prerequisites

• Node.js 24+
• A Fakturia account with API access enabled (how to get an API key)

Usage with Claude Code

Add the following to your project's .mcp.json or ~/.claude/.mcp.json for global access:

{
  "mcpServers": {
    "fakturia": {
      "command": "npx",
      "args": ["-y", "@edjufy/fakturia-mcp"],
      "env": {
        "FAKTURIA_API_HOST": "https://api.sandbox.fakturia.de",
        "FAKTURIA_API_KEY": "<your-api-key>"
      }
    }
  }
}

Replace <your-api-key> with your Fakturia API key. Use https://api.fakturia.de for production.

Usage with other MCP clients

This server communicates over stdio. Run it with the required environment variables:

FAKTURIA_API_HOST=https://api.sandbox.fakturia.de FAKTURIA_API_KEY=<your-api-key> npx -y @edjufy/fakturia-mcp

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | FAKTURIA_API_HOST | Yes | API base URL (see API Hosts) | | FAKTURIA_API_KEY | Yes | Your Fakturia API key (see Getting an API Key) | | FAKTURIA_API_INSECURE | No | Set to 1 to disable TLS certificate validation (local dev only) |

API Hosts

| Environment | API Host | Backoffice | |-------------|----------|------------| | Production | https://api.fakturia.de | backoffice.fakturia.de | | Sandbox | https://api.sandbox.fakturia.de | backoffice.sandbox.fakturia.de |

API documentation is available at /documentation/ on each host (e.g. api.fakturia.de/documentation).

Tip: Use the sandbox environment for development and testing. It behaves identically to production but won't affect real data.

Getting an API Key

1. Log in to the Fakturia backoffice (backoffice.fakturia.de or backoffice.sandbox.fakturia.de for sandbox)
2. Make sure your Fakturia plan includes API access
3. Navigate to your project settings and configure the API interface (API-Schnittstelle konfigurieren)
4. Activate the API for the project
5. Generate an API key
6. Configure the IP whitelist for the project (add your client's IP address, or leave empty to allow all)

For more details, see the Fakturia Wiki: REST API.

⚠️ Warning: If your API key has write access, the MCP server can perform actions that create, modify, or permanently delete data in your Fakturia account (e.g. cancelling contracts, paying invoices, deleting customers). This is especially risky when used with AI assistants that may take actions autonomously. Consider using a read-only API key to prevent unintended changes — you can configure this in your Fakturia project settings under the API configuration.

Development

git clone https://github.com/edjufy/fakturia-mcp.git
cd fakturia-mcp
pnpm install          # Install dependencies
pnpm build            # Compile TypeScript to dist/
pnpm bundle           # Compile + bundle to bundle/fakturia-mcp.mjs
pnpm start            # Run from compiled dist/
pnpm release          # Create a new release (via release-it)

Links

• Fakturia Website
• Fakturia API Documentation
• Fakturia Wiki: REST API
• OpenAPI Spec (OpenAPI 3.0.1)
• Model Context Protocol

Built by

edjufy Software GmbH — building digital solutions for education. Find more of our open-source work on GitHub.

License

MIT