duebuddy-mcp
mcp-name: work.duebuddy/invoices
MCP server that reads incoming supplier invoices and returns structured data plus a file ready for accounting. One endpoint for PDF, photos, scans, QR bills and electronic invoices.
Works with Claude Desktop, Cursor, Cline, Windsurf and any MCP client that supports stdio.
pip install duebuddy-mcp
DUEBUDDY_API_KEY=your-key duebuddy-mcp
Hosted alternative: https://duebuddy.work/mcp (streamable HTTP), no install needed.
Docs: https://duebuddy.work/mcp-docs
Why this exists
An accountant receives forty invoices a quarter. Half of them already contain the data in
machine-readable form — ZUGFeRD, XRechnung, Factur-X, FatturaPA, Peppol, KSeF, UBL — but they
arrive as invoice.pdf, so they get retyped by hand. The other half are scans and phone photos
where no data exists at all. This server handles both cases and returns fields plus an import
file, so the human checks instead of retyping.
Quick start
1. Get an API key
Sign up at https://duebuddy.work, open the cabinet, create an API key. Five invoices are free, no card required.
2. Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
%APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"duebuddy": {
"command": "duebuddy-mcp",
"env": { "DUEBUDDY_API_KEY": "your-key" }
}
}
}
3. Cursor
.cursor/mcp.json in your project:
{
"mcpServers": {
"duebuddy": {
"command": "duebuddy-mcp",
"env": { "DUEBUDDY_API_KEY": "your-key" }
}
}
}
4. Ask
Read the invoice at https://duebuddy.work/files/invoice-218.pdf, country de, and give me supplier, number, date, net, VAT, gross and the DATEV export link.
The assistant calls parse_invoice, then polls get_result, then reports.
Tools
| Tool | What it does | When to use | When NOT to use | Cost |
|---|---|---|---|---|
parse_invoice |
Reads one invoice, returns job_id |
One document needs field extraction | The user wants to issue an invoice, take a payment or post entries | XML and QR free; scans 0.07 EUR per page |
get_result |
Status, fields, export links for a job_id |
You already have a job_id |
You have no job_id yet |
free, read-only |
get_balance |
Remaining prepaid pages | Before a batch; after insufficient_balance |
The question is about invoice content | free, read-only |
topup_link |
Top-up page URL, minimum 8 EUR | Balance is empty or too low | Balance is sufficient | free, builds a link only |
Prompt invoice_to_accounting returns a safe order of operations for a batch: check balance,
parse each document, poll, validate totals, report.
What it reads
| Input | Example | Cost |
|---|---|---|
| XML e-invoice | ZUGFeRD, XRechnung, Factur-X, FatturaPA, Peppol BIS, KSeF, UBL, ZATCA, 1C/УПД/ЭСФ | free |
| PDF with embedded XML | ZUGFeRD 2.x, Factur-X | free |
| Text PDF | ordinary invoice export | per page |
| Scan or phone photo | JPG, PNG, PDF from scanner | 0.07 EUR per page |
| QR bill | Swiss and similar payment slips | free |
Country profiles select field names and tax rules: de, fr, it, pl, ru, kz, by,
us, ae, sa, ua, ge. The profile does not change the price.
Output
Structured fields: supplier, invoice number, issue date, due date, currency, net, VAT, gross, line items. Export files: DATEV EXTF category 21, CSV, Excel, JSON. The file is what accounting systems import — the server does not post entries itself.
Cost model
Prepaid balance, charged per scanned page. XML and QR invoices are parsed by code and cost nothing. No subscription is required to try it: five invoices are free.
What it does not do
- does not issue or send invoices
- does not take payments
- does not post entries into 1C or DATEV, it produces the file those systems import
- does not store your documents beyond processing
Configuration
| Variable | Default | Meaning |
|---|---|---|
DUEBUDDY_API_KEY |
– | API key, so it need not be passed on every call |
DUEBUDDY_BASE_URL |
https://duebuddy.work |
API endpoint |
DUEBUDDY_TIMEOUT |
90 |
HTTP timeout, seconds |
CLI
duebuddy-mcp --version # print version
duebuddy-mcp --help # usage
duebuddy-mcp --list-tools # tool names without starting the server
Docker
docker build -t duebuddy-mcp .
docker run -i --rm -e DUEBUDDY_API_KEY=your-key duebuddy-mcp
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
api_key_required |
No key passed and env var unset | add api_key argument or DUEBUDDY_API_KEY |
insufficient_balance |
Prepaid balance is empty | topup_link → top up from 8 EUR |
invalid_file_url |
URL is not https or not on duebuddy.work | upload the file to the cabinet first |
unsupported_country |
Country code outside the list | use one of the 12 supported codes |
| Server exits at once in a terminal | Transport is stdio | run it from an MCP client, not manually |
Security
The server only reads documents. It never posts entries, never issues invoices and never takes
payments. file_url must be an https link on duebuddy.work; redirects and other hosts are
rejected to prevent server-side request forgery. Each call is one HTTP request; nothing is cached
between calls.
License
MIT
Metadata
Release files for duebuddy-mcp 1.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| duebuddy_mcp-1.1.1.tar.gz | 8.5 kB | Without provenance | Details for duebuddy_mcp-1.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| duebuddy_mcp-1.1.1-py3-none-any.whl | Python 3 | none | any | Details for duebuddy_mcp-1.1.1-py3-none-any.whl |
Total release size: 18.3 kB
Release files / duebuddy_mcp-1.1.1.tar.gz
| Download URL | duebuddy_mcp-1.1.1.tar.gz |
|---|---|
| Size | 8.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b0bf25be5bd134116f74ab369134282076c46dda12165cdf7ffc1b8136ab987f
|
|
BLAKE2b-256 checksum How to use checksums |
8b140e778f77ebd60931094a567686062eecbbff4311dd83fa43da381f946efc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / duebuddy_mcp-1.1.1-py3-none-any.whl
| Download URL | duebuddy_mcp-1.1.1-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f1cd8a3f4a01e0824e02ae93e26ae4a67a8fbc5b621e0338fba3b2a286c14b30
|
|
BLAKE2b-256 checksum How to use checksums |
2213a2c70daa90bd216a0d82d72e871c6cd7388cd66cec9dd32e766f98828df5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Security for duebuddy-mcp 1.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.