PHPackages dg/pohoda-mcp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. dg/pohoda-mcp ActiveProject[API Development](/categories/api) dg/pohoda-mcp ============= MCP server pro účetní software Pohoda. Umožňuje AI asistentům číst a vytvářet faktury, objednávky, zásoby, kontakty a další agendy přes mServer XML API. v0.0.3(1mo ago)14114MITPHPPHP >=8.1 Since Jun 1Pushed 1w ago1 watchersCompare [ Source](https://github.com/dg/pohoda-mcp)[ Packagist](https://packagist.org/packages/dg/pohoda-mcp)[ RSS](/packages/dg-pohoda-mcp/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependencies (6)Versions (3)Used By (0) Pohoda MCP Server ================= [](#pohoda-mcp-server) MCP server pro účetní software [Pohoda](https://www.stormware.cz/pohoda/) od Stormware. Komunikuje s Pohodou přes [mServer XML API](https://www.stormware.cz/pohoda/xml/mserver/). Propojte svého AI asistenta přímo s účetnictvím. Ptejte se na faktury, procházejte adresář, kontrolujte zásoby, vytvářejte nové doklady nebo si nechte vytisknout fakturu do PDF. Stačí napsat, co potřebujete, a MCP server se postará o komunikaci s Pohodou. Požadavky --------- [](#požadavky) - PHP 8.1+ - ext-curl, ext-dom, ext-simplexml - Pohoda s aktivním mServerem (schéma verze 2) Nastavení mServeru v Pohodě --------------------------- [](#nastavení-mserveru-v-pohodě) Před použitím MCP serveru je potřeba v Pohodě zapnout a nakonfigurovat mServer. ### 1. Otevření správy mServeru [](#1-otevření-správy-mserveru) V programu Pohoda otevřete agendu **Účetní jednotky**, v menu zvolte **Databáze > POHODA mServer**. [![Otevření správy mServeru](doc/mServer-nastaveni.png)](doc/mServer-nastaveni.png) ### 2. Správa konfigurací [](#2-správa-konfigurací) Otevře se dialogové okno se seznamem konfigurací mServeru. Pro každou konfiguraci je uveden název, port, stav spuštění, host a PID. [![Správa mServeru](doc/mServer-sprava.png)](doc/mServer-sprava.png) ### 3. Vytvoření nové instance [](#3-vytvoření-nové-instance) Klikněte na **Nový** a na záložce **Základní** nastavte: - **Název** mServeru - **Účetní jednotku**, se kterou bude mServer komunikovat - **Port** pro komunikaci (výchozí 444) [![Nastavení instance](doc/mServer-nastaveni-instance.png)](doc/mServer-nastaveni-instance.png) Na záložce **HTTPS** lze zapnout zabezpečenou komunikaci: [![Nastavení HTTPS](doc/mServer-nastaveni-instance-HTTPS.png)](doc/mServer-nastaveni-instance-HTTPS.png) Na záložce **Monitoring** lze zapnout logování komunikace: [![Nastavení monitoringu](doc/mServer-nastaveni-instance-monitoring.png)](doc/mServer-nastaveni-instance-monitoring.png) ### 4. Spuštění [](#4-spuštění) Vyberte konfiguraci a klikněte na **Spustit** (nebo dvakrát klikněte na záznam). mServer začne naslouchat na nastaveném portu. Alternativně lze mServer ovládat z příkazové řádky pomocí přepínače `/HTTP`nad `pohoda.exe`. Jako poslední parametr se uvádí název konfigurace (v uvozovkách, pokud obsahuje mezery): ``` & "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP start "eShop-1" & "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP stop "eShop-1" & "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP restart "eShop-1" & "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP list ``` Další příkazy: `stop /f` (vynucené ukončení), `list:xml` (výpis konfigurací do XML). Pro automatické spuštění při startu systému Stormware doporučuje **Plánovač úloh Windows** (ne Windows službu). Podrobnosti viz [dokumentace Stormware](https://www.stormware.cz/pohoda/xml/mserver/spusteni/). Instalace MCP serveru --------------------- [](#instalace-mcp-serveru) ``` git clone https://github.com/dg/pohoda-mcp.git cd pohoda-mcp composer install ``` Konfigurace ----------- [](#konfigurace) Server se konfiguruje přes proměnné prostředí: ProměnnáPopisVýchozí`POHODA_URL`URL mServeru`http://localhost:444``POHODA_ICO`ICO účetní jednotky`POHODA_USERNAME`Uživatelské jméno pro mServer`POHODA_PASSWORD`Heslo`POHODA_EXE_PATH`Cesta k `Pohoda.exe` pro autostart mServeru (volitelné)`POHODA_CONFIG_NAME`Název konfigurace mServeru pro autostart (volitelné)Pokud jsou nastaveny `POHODA_EXE_PATH` a `POHODA_CONFIG_NAME`, server před prvním tool callem ověří, že mServer běží — pokud ne, sám ho spustí přes `pohoda.exe /HTTP start`. Při ukončení MCP serveru ho zase zastaví, ale jen pokud ho sám startoval (pokud mServer už běžel, necháme ho běžet). Windows-only (mServer je součást Pohody). Použití v agentech (např. Claude Code) -------------------------------------- [](#použití-v-agentech-např-claude-code) Přidejte do `.mcp.json` nebo do project settings: ``` { "mcpServers": { "pohoda": { "command": "php", "args": ["/cesta/k/pohoda-mcp/server.php"], "env": { "POHODA_URL": "http://localhost:444", "POHODA_ICO": "12345678", "POHODA_USERNAME": "Admin", "POHODA_PASSWORD": "", "POHODA_EXE_PATH": "C:\\Program Files (x86)\\STORMWARE\\POHODA\\Pohoda.exe", "POHODA_CONFIG_NAME": "mServer1" } } } } ``` Poslední dvě proměnné jsou volitelné — slouží k automatickému spuštění mServeru při prvním tool callu (viz výše). Dostupné nástroje ----------------- [](#dostupné-nástroje) ### status [](#status) Ověří, jestli mServer běží a odpovídá. Základní volání vrací pouze stručný text z `GET /status` (Pohoda odpovídá prostým stringem, ne XML). S parametrem `companyDetail=true` navíc přes autentizovaný dotaz vrátí název účetní jednotky, název databáze a aktuální účetní rok. ParametrPopis`companyDetail``true`/`false` — vrátit i údaje o aktivní účetní jednotce (default `false`)### list\_documents, list\_stock, list\_contacts [](#list_documents-list_stock-list_contacts) Tři čtecí nástroje rozdělené podle druhu záznamu. Niche/číselníkové agendy (`centre`, `activity`, `store`, `bankAccount`, `cashRegister`, `numericalSeries`) nejsou dostupné přes dedikovaný tool, použij `raw_xml`. #### list\_documents [](#list_documents) Doklady. Parametr `agenda` — jedna z následujících: AgendaPopisAgendaPopis`invoice`faktury\*`prijemka`příjemky`order`objednávky`vydejka`výdejky`voucher`pokladní doklady`prodejka`prodejky`bank`banka`prevodka`převodky`contract`zakázky`vyroba`výroba`intDoc`interní doklady`accountancy`účetní deník`offer`nabídky`enquiry`poptávky\* Agenda `invoice` vyžaduje parametr `invoiceType`: `issuedInvoice` nebo `receivedInvoice`. Filtry: `id`, `dateFrom`, `dateTill`, `company`, `ico`, `number`(přesná shoda celé hodnoty, ne substring), `lastChanges`(záznamy změněné od `YYYY-MM-DDThh:mm:ss`), `limit` (default 100, klientský ořez). #### list\_stock [](#list_stock) Zásoby. Filtry: `id`, `code`, `name`, `EAN`, `storage`(cesta ve členění skladu, např. `"ZBOZI/Elektro"`), `store` (zkratka skladu), `internet` (true/false), `lastChanges`, `limit`. #### list\_contacts [](#list_contacts) Adresář. Filtry: `id`, `company`, `ico`, `lastChanges`, `limit`. ### create\_invoice [](#create_invoice) Vytvoření vydané nebo přijaté faktury. Podporuje: - adresu partnera přímo nebo vazbu na adresář (`partnerId`) - variabilní symbol, datum splatnosti, datum zdanitelného plnění - předkontaci, způsob platby, bankovní účet - středisko, činnost, zakázku - cizí měnu s kurzem - položky s vazbou na skladovou kartu (`stockCode`) ### create\_address [](#create_address) Vytvoření záznamu v adresáři (firma/kontakt). ### create\_stock [](#create_stock) Vytvoření skladové karty. Kromě základních údajů (kód, název, cena) podporuje: - EAN, PLU pro pokladny - příznaky pro prodej a e-shop - popis, doplněk názvu, krátký název - minimální a maximální zásobu, hmotnost - dodavatele, záruku ### create\_order [](#create_order) Vytvoření přijaté nebo vydané objednávky s položkami. ### print [](#print) Tisk nebo export do PDF libovolného záznamu. Umí: - tisk na tiskárnu (výchozí nebo konkrétní) - export do PDF souboru na serveru (`pdfPath` je povinný pro PDF cestu) - vrácení PDF jako Base64 přímo v odpovědi (`pdfBase64=true`, vyžaduje `pdfPath`) Agenda se zadává česky: `vydane_faktury`, `prijate_faktury`, `zasoby`, `adresar`, `pokladna`, `banka`, `interni_doklady`, `zakazky`, `vydejky`, `prijemky`, `prodejky`, `vydane_objednavky`, `prijate_objednavky`, `vydane_nabidky`, `prijate_nabidky` atd. ID tiskové sestavy (`reportId`) se liší podle instalace a vlastních úprav. V Pohodě ho zjistíte v **Editoru tiskových sestav** (menu Soubor → Tiskové sestavy), kde u každé sestavy vidíte sloupec ID, nebo přes pravé tlačítko myši na sestavě v dialogu tisku → **Vlastnosti**. Standardní dodávané sestavy mají ID v řádech stovek až tisíců (typicky 200–3000+). ### raw\_xml [](#raw_xml) Odeslání libovolného XML. Pokrývá případy, na které ostatní nástroje nestačí. XML se vloží přímo do `` obálky, musí tedy obsahovat vlastní namespace deklarace. Referenční zdroje (MCP resources) --------------------------------- [](#referenční-zdroje-mcp-resources) Číselníky povolených hodnot jsou vystavené jako MCP resources, takže si je klient může vyzvednout bez tool callu: URIObsah`pohoda://enums/agendas`seznam agend rozdělený podle toho, který list tool je pokrývá`pohoda://enums/vat-rates`povolené hodnoty `vatRate` u položek (`none`, `low`, `high`)`pohoda://enums/payment-types`hodnoty `paymentType` faktur (`draft`, `cash`, `card`, `compensation`)`pohoda://enums/print-agendas`české názvy agend přijímané `print`Použití z PHP kódu (bez MCP) ---------------------------- [](#použití-z-php-kódu-bez-mcp) Knihovnu lze použít i přímo jako PHP klienta pro mServer, nezávisle na MCP. Hodí se pro vlastní skripty, cronjoby nebo integraci do existující aplikace. ``` use DG\Pohoda\PohodaClient; $client = new PohodaClient( url: 'http://localhost:444', ico: '12345678', username: 'Admin', password: '', ); // Najdi fakturu podle čísla dokladu $list = $client->listRecords('invoice', ['number' => '26010192'], 'issuedInvoice'); $faId = (int) $list->items[0]->data['invoice'][0]['invoiceHeader']['id']; // Vytiskni ji do PDF $client->printRecord([ 'agenda' => 'vydane_faktury', 'recordId' => $faId, 'reportId' => 3000, 'pdfPath' => 'C:\\tmp\\faktura.pdf', ]); ``` Veřejné metody `PohodaClient`: `getStatus()`, `listRecords()`, `createInvoice()`, `createAddress()`, `createStock()`, `createOrder()`, `printRecord()`, `sendRawXml()`. ### Spouštění a zastavování mServeru [](#spouštění-a-zastavování-mserveru) Pokud skript nemůže předpokládat, že je mServer už spuštěný, hodí se třída `MServerController`. Je to tenký obal nad `pohoda.exe /HTTP start|stop`, který spouští Pohodu non-blocking a po startu polluje `PohodaClient::getStatus()`, dokud mServer nezačne odpovídat. Windows-only. Nejjednodušší cesta je předat ho `PohodaClient`u — ten si pak sám lazy nastartuje mServer před prvním HTTP requestem a při destrukci ho zase zastaví (jen pokud ho sám startoval; pokud už běžel, necháme ho běžet): ``` use DG\Pohoda\MServerController; use DG\Pohoda\PohodaClient; $client = new PohodaClient(url: 'http://127.0.0.1:555', ico: '12345678', username: 'Admin', password: ''); $client->setController(new MServerController( exePath: 'C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe', configName: 'mServer1', )); // ... práce s $client — autostart se postará o sebe ... ``` Pokud chceš lifecycle řídit ručně, controller umí stejné věci přímo: ``` $ctrl = new MServerController(exePath: '...', configName: 'mServer1'); $wasRunning = false; try { $client->getStatus(); $wasRunning = true; } catch (\RuntimeException) { $ctrl->start($client); // vrátí se až když mServer odpovídá (nebo vyhodí po timeoutu) } // ... práce s $client ... if (!$wasRunning) { $ctrl->stop(); } ``` Při volání HTTP endpointů používej `http://127.0.0.1:555`, ne `http://localhost:555`— PHP resolver zkouší pro `localhost` nejdřív IPv6 (`::1`), kam mServer nenaslouchá, a čeká se zbytečně na timeout. Veřejné metody `MServerController`: - `start(PohodaClient $client, int $timeoutSeconds = 30)` — spustí Pohodu s `/HTTP start`, čeká až HTTP status API odpoví. Při timeoutu vyhodí `RuntimeException`. - `stop()` — pošle `/HTTP stop` fire-and-forget, nečeká na ukončení. Řešení problémů --------------- [](#řešení-problémů) SymptomPravděpodobná příčina`Curl Error: Connection refused`mServer neběží; spusť ho v Pohodě nebo přes `pohoda.exe /HTTP start``HTTP 401`Chybné `POHODA_USERNAME` / `POHODA_PASSWORD`Odpověď je HTML s přihlašovací stránkouUživatel v Pohodě nemá práva na mServer nebo je agenda otevřená jinou instancí`state="error"` + `note="Nepodařila se validace dokumentu podle schématu"`Špatná struktura XML — typicky zaměněný namespace nebo chybějící povinný element; text chyby ukazuje na element`listRecords` vrací prázdný seznammServer je připojený na jinou účetní jednotku/rok, než kde doklad žije (zkontroluj `status` s `companyDetail=true`)`pdfPath` je vytvořen, ale nejde otevřít (0 B)mServer nemá práva zapisovat na dané místo — zkus výchozí `D:\Data\ucto\Tisk\` nebo dočasný adresář uživatele, pod kterým Pohoda běží`Print` vrací OK, ale PDF nevzniká`reportId` neexistuje v instalaci; ověř ID v Editoru tiskových sestavStruktura projektu ------------------ [](#struktura-projektu) ``` server.php vstupní bod MCP serveru (stdio transport) src/ McpTools.php tenký MCP adaptér (#[McpTool] atributy) PohodaClient.php HTTP klient a doménové metody pro mServer API XmlBuilder.php stavba XML požadavků přes XMLWriter Response.php parsovaná odpověď z mServeru ResponseItem.php jeden záznam z odpovědi MServerController.php spouštění a zastavování mServeru přes pohoda.exe ``` Licence ------- [](#licence) MIT ### Health Score 40 — FairBetter than 86% of packages Maintenance96 Actively maintained with recent releases Popularity16 Limited adoption so far Community9 Small or concentrated contributor base Maturity33 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~17 days Total 2 Last Release 35d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/17f266513a3ca97500ec3d85d562b9279c7a6346358fe2b8d90390ece717a027?d=identicon)[david@grudl.com](/maintainers/david@grudl.com) --- Top Contributors [![dg](https://avatars.githubusercontent.com/u/194960?v=4)](https://github.com/dg "dg (5 commits)") --- Tags mcpaiinvoicesAccountingpohodaxml apistormwaremserver ### Code Quality Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/dg-pohoda-mcp/health.svg) ``` [![Health](https://phpackages.com/badges/dg-pohoda-mcp/health.svg)](https://phpackages.com/packages/dg-pohoda-mcp) ``` ### Alternatives [symfony/ai-mate AI development assistant MCP server for Symfony projects 28170.6k34](/packages/symfony-ai-mate)[wordpress/mcp-adapter Adapter for Abilities API, letting WordPress abilities to be used as MCP tools, resources or prompts 887184.7k8](/packages/wordpress-mcp-adapter)[alle-ai/anthropic-api-php The go-to PHP library for the Anthropic API — Messages, streaming, tool use, vision, prompt caching, extended thinking, MCP, Files, Batches. Maintained by Alle-AI. 2626.6k](/packages/alle-ai-anthropic-api-php) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)