Pohoda MCP

Pohoda MCP サーバー

Stormware の会計ソフトウェア Pohoda 用の MCP サーバーです。 Pohoda mServer XML API を介して Pohoda と通信します。

AI アシスタントを会計ソフトウェアに直接接続できます。請求書について質問したり、アドレス帳を参照したり、 在庫を確認したり、新しい書類を作成したり、請求書を PDF に印刷したりできます。必要なことを入力するだけで、 MCP サーバーが Pohoda との通信を処理します。

要件

• PHP 8.1+
• ext-curl, ext-dom, ext-simplexml
• mServer が有効になっている Pohoda（スキーマバージョン 2）

Pohoda での mServer の設定

MCP サーバーを使用する前に、Pohoda で mServer を有効にして設定する必要があります。

1. mServer 管理画面を開く

Pohoda で 会計単位 の画面を開き、メニューから データベース > POHODA mServer を選択します。

2. 設定の管理

mServer の設定一覧が表示されたダイアログが開きます。 各設定には、名前、ポート、起動状態、ホスト、PID が表示されます。

3. 新しいインスタンスを作成する

新規 をクリックし、基本 タブで次の項目を設定します。

• mServer の名前
• mServer が通信する会計単位
• 通信用のポート（デフォルトは 444）

HTTPS タブでは、安全な通信を有効にできます。

モニタリング タブでは、通信のログ記録を有効にできます。

4. 起動

設定を選択して 起動 をクリックします（または項目をダブルクリックします）。 mServer は設定されたポートでリッスンを開始します。

また、pohoda.exe に /HTTP オプションを指定して、コマンドラインから mServer を操作することもできます。最後のパラメーターには設定名を指定します（スペースを含む場合は引用符で囲みます）。

& "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

その他のコマンド：stop /f（強制終了）、list:xml（設定を XML 形式で一覧表示）。 システム起動時に自動起動するには、Stormware は Windows タスク スケジューラ（Windows サービスではありません）の使用を推奨しています。

詳細については、Stormware のドキュメントを参照してください。

MCP サーバーのインストール

git clone https://github.com/dg/pohoda-mcp.git
cd pohoda-mcp
composer install

設定

サーバーは環境変数で設定します。

変数	説明	デフォルト
POHODA_URL	mServer の URL	http://localhost:444
POHODA_ICO	会計事業体の ICO
POHODA_USERNAME	mServer のユーザー名
POHODA_PASSWORD	パスワード
POHODA_EXE_PATH	mServer の自動起動に使用する Pohoda.exe のパス（任意）
POHODA_CONFIG_NAME	自動起動する mServer の設定名（任意）

POHODA_EXE_PATH と POHODA_CONFIG_NAME が設定されている場合、サーバーは最初の ツール呼び出しの前に mServer が実行中かどうかを確認し、実行中でなければ pohoda.exe /HTTP start を使って自動的に起動します。 MCP サーバーの終了時には mServer も停止しますが、停止するのはサーバー自身が起動した場合のみです（mServer がすでに実行中だった場合は、そのまま実行を続けます）。Windows 専用です（mServer は Pohoda の一部です）。

エージェントでの使用（例：Claude Code）

設定例は .mcp.json.example ファイルにあります。これをコピーし、server.php への絶対パスと認証情報を追加します。最後の 2 つの変数は任意で、最初のツール呼び出し時に mServer を自動起動するために使用します（上記参照）。ファイルの配置場所はツールによって異なります。

ツール	配置場所
Claude Code	プロジェクトのルートにある .mcp.json
Claude Desktop	内容を %APPDATA%\Claude\claude_desktop_config.json に貼り付けます
Cursor	プロジェクト内の .cursor/mcp.json、またはすべてのプロジェクトで使用する場合は ~/.cursor/mcp.json
Gemini CLI	プロジェクト内の .gemini/settings.json、または ~/.gemini/settings.json
Windsurf	~/.codeium/windsurf/mcp_config.json

VS Code（Copilot）では servers キーを使用し、起動時にパスワードを入力できるため、ファイルに保存する必要はありません。.vscode/mcp.json に記述します。

{
	"inputs": [
		{"type": "promptString", "id": "pohoda-password", "description": "Heslo k mServeru", "password": true}
	],
	"servers": {
		"pohoda": {
			"type": "stdio",
			"command": "php",
			"args": ["/cesta/k/pohoda-mcp/server.php"],
			"env": {
				"POHODA_URL": "http://localhost:444",
				"POHODA_ICO": "12345678",
				"POHODA_USERNAME": "Admin",
				"POHODA_PASSWORD": "${input:pohoda-password}"
			}
		}
	}
}

OpenAI Codex CLI の設定は TOML 形式で、~/.codex/config.toml に記述します。

[mcp_servers.pohoda]
command = "php"
args = ["/cesta/k/pohoda-mcp/server.php"]
env = { POHODA_URL = "http://localhost:444", POHODA_ICO = "12345678", POHODA_USERNAME = "Admin", POHODA_PASSWORD = "" }

パスワードを含むファイルは絶対にコミットしないでください。 設定をプロジェクトに保存する場合は、.gitignore に追加してください。

利用可能なツール

status

mServer が実行中で応答するかを確認します。基本の呼び出しでは、GET /status から短いテキストのみを返します（Pohoda は XML ではなく、単純な文字列で応答します）。companyDetail=true パラメーターを指定すると、認証済みの問い合わせによって、会計事業体名、データベース名、現在の会計年度も返します。

パラメーター	説明
companyDetail	true/false — 有効な会計事業体の情報も返すか（デフォルトは false）

list_documents, list_stock, list_contacts

レコードの種類ごとに分かれた 3 つの読み取り専用ツールです。ニッチな業務領域／コード表の領域（centre、activity、store、bankAccount、cashRegister、numericalSeries）には専用ツールがないため、raw_xml を使用してください。

list_documents

書類です。agenda パラメーターには、次のいずれかを指定します。

Agenda	説明		Agenda	説明
invoice	請求書*		prijemka	入庫伝票
order	注文書		vydejka	出庫伝票
voucher	現金伝票		prodejka	販売伝票
bank	銀行		prevodka	倉庫間移動伝票
contract	案件		vyroba	製造
intDoc	内部伝票		accountancy	会計仕訳帳
offer	見積書
enquiry	引き合い

* invoice アジェンダには、invoiceType パラメーター（issuedInvoice または receivedInvoice）が必要です。

フィルター：id、dateFrom、dateTill、company、ico、number （値全体の完全一致で、部分文字列一致ではありません）、lastChanges （YYYY-MM-DDThh:mm:ss 以降に変更されたレコード）、limit（デフォルトは 100、クライアント側で切り詰めます）。

list_stock

在庫です。フィルター：id、code、name、ean、storage （倉庫内の階層パス。例："ZBOZI/Elektro"）、store（倉庫の略称）、 internet（true/false）、lastChanges、limit。

list_contacts

アドレス帳です。フィルター：id、company、ico、lastChanges、limit。

create_invoice

発行済みまたは受領済みの請求書を作成します。次をサポートします。

• 取引先住所の直接指定、またはアドレス帳との関連付け（partnerId）
• 変動シンボル、支払期限、課税対象取引日
• 勘定科目割り当て、支払方法、銀行口座
• 部門、業務、案件
• 為替レートを指定した外貨
• 倉庫カードとの関連付け（stockCode）を含む明細項目

create_address

アドレス帳のレコード（会社／連絡先）を作成します。

create_stock

倉庫カードを作成します。基本情報（コード、名称、価格）に加えて、次をサポートします。

• EAN、レジ用 PLU
• 販売およびオンラインストア向けのフラグ
• 説明、名称補足、短縮名
• 最小在庫数、最大在庫数、重量
• サプライヤー、保証

create_order

明細項目を含む、受領または発行済み注文書を作成します。

print

任意のレコードを印刷または PDF にエクスポートします。次の機能があります。

• プリンター（既定または指定）への印刷
• サーバー上の PDF ファイルへのエクスポート（PDF の出力先には pdfPath が必須です）
• PDF を Base64 形式で応答に直接返す（pdfBase64=true。pdfPath が必要です）

アジェンダにはチェコ語を指定します：vydane_faktury、prijate_faktury、zasoby、adresar、 pokladna、banka、interni_doklady、zakazky、vydejky、prijemky、prodejky、 vydane_objednavky、prijate_objednavky、vydane_nabidky、prijate_nabidky など。

印刷レポート ID（reportId）は、インストール環境やカスタマイズによって異なります。 Pohoda では、Editoru tiskových sestav（メニューの「Soubor → Tiskové sestavy」）で確認できます。 各レポートの ID 列に表示されます。または、印刷ダイアログでレポートを右クリックし、 Vlastnosti を選択して確認できます。標準で提供されるレポートの ID は通常、数百から数千 （一般的には 200～3000 以上）です。

参照リソース（MCP resources）

許可された値の列挙型は MCP リソースとして公開されているため、クライアントはツール呼び出しなしで取得できます。

URI	内容
pohoda://enums/agendas	各 list ツールが対応するアジェンダ別に分けた一覧
pohoda://enums/vat-rates	明細項目の vatRate に指定できる値（none、low、high）
pohoda://enums/payment-types	請求書の paymentType の値（draft、cash、card、compensation）
pohoda://enums/print-agendas	print で受け付けるチェコ語のアジェンダ名

PHP コードからの使用（MCP を使用しない場合）

このライブラリは、MCP とは独立して、mServer 用の PHP クライアントとして直接使用することもできます。 独自のスクリプト、cron ジョブ、既存アプリケーションへの統合に適しています。

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',
]);

PohodaClient の公開メソッド：getStatus()、listRecords()、createInvoice()、 createAddress()、createStock()、createOrder()、printRecord()、sendRawXml()。

mServer の起動と停止

スクリプトで mServer がすでに起動していると仮定できない場合は、 MServerController クラスが便利です。これは pohoda.exe /HTTP start|stop の薄いラッパーで、 Pohoda をノンブロッキングで起動し、起動後は mServer が応答を開始するまで PohodaClient::getStatus() をポーリングします。Windows 専用です。

最も簡単な方法は、PohodaClient に渡すことです。そうすると、最初の HTTP リクエストの前に mServer を遅延起動し、破棄時に停止します（自分で起動した場合のみ。すでに起動していた場合は そのまま実行し続けます）。

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 ...

ライフサイクルを手動で管理したい場合、コントローラーから同じ操作を直接実行できます。

$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();
}

HTTP エンドポイントを呼び出すときは、http://localhost:555 ではなく http://127.0.0.1:555 を使用してください。PHP のリゾルバーは localhost に対して最初に IPv6（::1）を試しますが、 mServer はそのアドレスで待ち受けていないため、不要なタイムアウト待ちが発生します。

MServerController の公開メソッド：

• start(PohodaClient $client, int $timeoutSeconds = 30) — /HTTP start を使用して Pohoda を起動し、 HTTP ステータス API が応答するまで待機します。タイムアウトすると RuntimeException をスローします。
• stop() — /HTTP stop を送信し、完了を待たずに処理を終了します。

トラブルシューティング

症状	考えられる原因
Curl Error: Connection refused	mServer が実行されていません。Pohoda 内で、または pohoda.exe /HTTP start を使って起動してください
HTTP 401	POHODA_USERNAME / POHODA_PASSWORD が間違っています
応答がログインページの HTML になっている	Pohoda のユーザーに mServer の権限がないか、別のインスタンスで会計データベースが開かれています
state="error" + note="Nepodařila se validace dokumentu podle schématu"	XML の構造が正しくありません。典型的な原因は、名前空間の取り違えまたは必須要素の欠落です。エラーテキストに問題の要素が示されます
listRecords が空の一覧を返す	mServer が、伝票が保存されているものとは異なる会社／会計年度に接続されています（companyDetail=true を指定して status を確認してください）
pdfPath が作成されるが開けない（0 B）	mServer に該当場所への書き込み権限がありません。デフォルトの D:\Data\ucto\Tisk\ または Pohoda の実行ユーザーの一時ディレクトリを試してください
Print は OK を返すが PDF が作成されない	reportId がインストール環境に存在しません。印刷レポートエディターで ID を確認してください

プロジェクト構成

server.php                 vstupní bod MCP serveru (stdio transport)
.mcp.json.example          vzorová konfigurace MCP klienta
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

ライセンス

MIT