Fakturaonline MCP

Faktura Online MCP Server


Model Context Protocol (MCP) server, který umožňuje Claude (a jiným AI asistentům) pracovat s Faktura Online. Pomocí tohoto serveru můžete Claude požádat o vytvoření faktury, seznam kontaktů, stažení reportů a další.

Co to umí:

• Vytvářet, upravovat a mazat faktury
• Odesílat faktury emailem
• Spravovat kontakty
• Exportovat faktury do PDF, XML, ISDOC
• Generovat reporty
• Hromadné operace nad fakturami

🚀 Instalace

Máte dvě možnosti nasazení:

Varianta A: Lokální MCP Server (stdio)

Pro použití s Claude Desktop na vašem počítači.

Claude Desktop konfigurace

Upravte konfigurační soubor:

macOS: ~/.claude.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fakturaonline": {
      "command": "npx",
      "args": ["-y", "github:fakturaonline/fakturaonline-mcp"],
      "env": {
        "FAKTURAONLINE_EMAIL": "vas@email.cz",
        "FAKTURAONLINE_PASSWORD": "vase_heslo",
        "FAKTURAONLINE_API_BASE": "https://api.fakturaonline.cz/v0"
      }
    }
  }
}

Alternativně s JWT tokenem:

"env": {
  "FAKTURAONLINE_TOKEN": "vase_jwt_token",
  "FAKTURAONLINE_API_BASE": "https://api.fakturaonline.cz/v0"
}

Poznámka: FAKTURAONLINE_API_BASE je volitelné - výchozí hodnota je produkční API. FAKTURAONLINE_EXPORT_DIR je volitelné - určuje povolenou složku pro ukládání souborů přes file_path u export toolů (výchozí ./exports).

Lokální instalace (pro vývoj)

git clone https://github.com/fakturaonline/fakturaonline-mcp.git
cd fakturaonline-mcp
npm install
npm run build

Pak v konfiguraci použijte cestu k lokálnímu souboru:

{
  "mcpServers": {
    "fakturaonline": {
      "command": "node",
      "args": ["/cesta/k/fakturaonline-mcp/dist/index.js"],
      "env": {
        "FAKTURAONLINE_EMAIL": "vas@email.cz",
        "FAKTURAONLINE_PASSWORD": "vase_heslo",
        "FAKTURAONLINE_API_BASE": "https://api.fakturaonline.cz/v0"
      }
    }
  }
}

HTTP cassette replay pro CI

Integration testy lze spouštět bez živého API přes JSON cassette soubory v tests/cassettes.

Replay v CI:

npm run test:integration:replay

Lokální nahrání nebo obnova cassette scénáře:

FAKTURAONLINE_CASSETTE_SCENARIO=mcp/list-invoices npm run test:integration:record

Volitelné proměnné:

• FAKTURAONLINE_CASSETTE_DIR pro vlastní adresář s cassette soubory
• FAKTURAONLINE_CASSETTE_TARGET pro jiný integrační test než tests/integration/mcp-server.test.ts
• běžné FAKTURAONLINE_* přihlašovací proměnné, pokud se scénář nahrává proti živému API

Varianta B: Cloudflare Workers (remote)

Pro použití s Claude Web rozhraním nebo jakýmkoli remote MCP klientem.

🌐 Veřejný MCP server

Nemusíte nic instalovat ani deployovat - můžete použít náš veřejný MCP server:

https://mcp.fakturaonline.cz/mcp

🎯 Návod: Připojení k Claude Web (krok za krokem)

Tento návod vás provede připojením Faktura Online MCP serveru k webové verzi Claude na claude.ai. Zvládne to i úplný začátečník!

Co budete potřebovat

• ✅ Účet na claude.ai (stačí bezplatný)
• ✅ Účet na Faktura Online
• ✅ Webový prohlížeč (Chrome, Firefox, Safari...)

Krok 1: Otevřete nastavení Claude

1. Přejděte na claude.ai a přihlaste se
2. Klikněte na ikonu ozubeného kolečka (⚙️) v levém dolním rohu
3. V menu vyberte Settings (Nastavení)

Krok 2: Přejděte do sekce Connectors

1. V levém panelu nastavení klikněte na Connectors
2. Uvidíte seznam již připojených konektorů
3. Klikněte na tlačítko Add more (Přidat další)

Nastavení integrací v Claude

Krok 3: Přidejte MCP server

1. V dialogu pro přidání integrace vyberte MCP nebo Custom integration
2. Do pole Integration URL zadejte:

   https://mcp.fakturaonline.cz/mcp

1. Klikněte na Connect (Připojit)

Přidání MCP URL

Krok 4: Přihlaste se k Faktura Online

Po připojení MCP serveru je potřeba se přihlásit k vašemu účtu Faktura Online:

1. Vraťte se do chatu s Claude
2. Napište Claude zprávu, například:

   Přihlas mě do Faktura Online s emailem jan@example.cz a heslem mojeHeslo123

1. Claude použije nástroj sign_in a přihlásí vás

Přihlášení přes Claude

⚠️ Bezpečnostní tip: Heslo se posílá přímo na API Faktura Online přes šifrované spojení (HTTPS). Claude si heslo nepamatuje a neukládá ho.

Krok 5: Začněte používat! 🎉

Teď můžete Claude požádat o cokoli souvisejícího s fakturami:

Ty: Ukaž mi seznam mých posledních faktur
Claude: [používá list_invoices] Tady jsou vaše poslední faktury...

Ty: Vytvoř fakturu pro firmu ABC s.r.o. na 5000 Kč za konzultace
Claude: [používá create_invoice] Faktura byla vytvořena...

Řešení problémů

❌ "MCP server not responding"

• Zkontrolujte, že URL je správně: https://mcp.fakturaonline.cz/mcp
• Zkuste obnovit stránku (F5)
• Počkejte minutu a zkuste znovu (server se možná restartuje)

❌ "Authentication failed"

• Zkontrolujte email a heslo k Faktura Online
• Ujistěte se, že váš účet na Faktura Online je aktivní
• Zkuste se přihlásit přímo na app.fakturaonline.cz

❌ Claude nevidí nástroje pro faktury

• Ujistěte se, že konektor je správně připojený (Settings → Connectors)
• Zkuste konektor odpojit a znovu připojit
• Restartujte prohlížeč

❌ "Session expired"

• Stačí se znovu přihlásit: Přihlas mě do Faktura Online...
• Session vyprší po určité době neaktivity

Vlastní deploy (volitelné)

Pokud chcete provozovat vlastní MCP server:

git clone https://github.com/fakturaonline/fakturaonline-mcp.git
cd fakturaonline-mcp/workers

# Vyžaduje Node.js 20+
nvm use 20

npm install
npx wrangler login
npm run deploy

Po deployi dostanete URL:

https://fakturaonline-mcp..workers.dev/mcp

Připojení k Claude Desktop (přes proxy)

{
  "mcpServers": {
    "fakturaonline": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.fakturaonline.cz/mcp"
      ]
    }
  }
}

Tip: Místo veřejného serveru můžete použít vlastní URL: https://fakturaonline-mcp..workers.dev/mcp

Autentizace uživatelů

Workers verze podporuje multi-tenant režim - každý uživatel se přihlásí svým vlastním Faktura Online účtem pomocí tool sign_in.

💻 Jak to používat

Po připojení můžete s Claude mluvit přirozeně:

Ty: Vytvoř fakturu na službu vývoje aplikace pro Novák s.r.o., 10000 Kč bez DPH.

Claude: Samozřejmě. Pro vytvoření faktury potřebuji vědět:
- Datum vystavení
- Kontakt (vyberu ze seznamu nebo vytvořím nový)
- Daňové sazby

...

Claude: Faktura byla úspěšně vytvořena. Číslo: 2024001, celková částka: 12100 Kč včetně DPH.

Příklady, co můžete dělat

Práce s fakturami:

- "Ukaž mi všechny nezaplacené faktury"
- "Vytvoř fakturu pro Firma s.r.o. na 5 hodin konzultací po 2000 Kč"
- "Označ fakturu číslo 1234 jako zaplacenou"
- "Exportuj fakturu 1234 do PDF"
- "Vytvoř dobropis k faktuře 1234"

Odesílání emailem:

- "Pošli fakturu 1234 emailem na jan@firma.cz"
- "Zobraz mi náhled emailu pro fakturu 1234"
- "Pošli fakturu s kopií na můj email"
- "Jaké emaily mám v historii?"

Práce s kontakty:

- "Seznam kontaktů"
- "Přidej nový kontakt: Jan Novák, IČ 12345678, Praha"
- "Najdi kontakt s názvem 'Firma s.r.o.'"

Reporty:

- "Jaký byl obrat v listopadu?"
- "Pošli mi report za poslední kvartál na email"
- "Exportuj report faktur za letošní rok"

📚 Přehled všech funkcí

Autentizace

Poznámka: U lokální varianty s nastavenými env proměnnými se server přihlásí automaticky.

Faktury

Export

Odesílání emailem

Kontakty

Reporty

Vyhledávání firem

📝 Příklad: Vytvoření faktury

create_invoice({
  number: "2024010001",
  issued_on: "2024-01-15",
  currency: "CZK",
  language: "cs",
  kind: "invoice",
  buyer_attributes: {
    name: "Firma s.r.o.",
    company_number: "12345678",
    street: "Ulice 123",
    city: "Praha",
    postcode: "11000",
    country_code: "CZ"
  },
  lines_attributes: [
    {
      description: "Web development",
      price: "10000",
      quantity: "1",
      vat_rate: "0"
    }
  ]
})

🔗 Užitečné odkazy

• Faktura Online - Hlavní aplikace
• API Dokumentace - Detailní API docs
• MCP Protocol - O protokolu

📄 Licence

MIT License

🤝 Podpora

Pro dotazy a podporu použijte:

• Email: info@fakturaonline.cz
• Web: https://www.fakturaonline.cz