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