Pohoda MCP

Pohoda MCP 服务

用于 Stormware 会计软件 Pohoda 的 MCP 服务。 通过 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，但仅当它是由 MCP 服务启动时才会停止（如果 mServer 已在运行，则会让它继续运行）。仅限 Windows（mServer 是 Pohoda 的组成部分）。

在 Agent 中使用（例如 Claude Code）

现成的配置位于文件 .mcp.json.example 中。复制该文件并补充 server.php 的绝对路径和访问凭据。最后两个变量是可选的，用于在首次工具调用时自动启动 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

三个读取工具，按记录类型划分。小众／代码表类业务模块 （centre、activity、store、bankAccount、cashRegister、numericalSeries） 无法通过专用工具访问，请使用 raw_xml。

list_documents

单据。参数 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）
• 在响应中直接以 Base64 返回 PDF（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 的 打印报表编辑器中可以查看（菜单“文件” → “打印报表”）， 每个报表旁都有 ID 列；也可以在打印对话框中右键单击报表 → 属性。标准附带的报表 ID 通常为数百到数千（一般为 200–3000+）。

参考资源（MCP resources）

允许值的枚举以 MCP resources 形式提供，客户端无需调用工具即可获取：

URI	内容
pohoda://enums/agendas	按各列表工具覆盖范围划分的业务类型列表
pohoda://enums/vat-rates	项目中 vatRate 的允许值（none、low、high）
pohoda://enums/payment-types	发票 paymentType 的值（draft、cash、card、compensation）
pohoda://enums/print-agendas	print 接受的捷克语业务类型名称

在 PHP 代码中使用（不使用 MCP）

此库也可以直接作为 PHP 客户端用于 mServer，独立于 MCP。 适用于自定义脚本、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，并在启动后轮询 PohodaClient::getStatus()，直到 mServer 开始响应。仅适用于 Windows。

最简单的方式是将它传给 PohodaClient，这样客户端会在第一次 HTTP 请求前自动延迟启动 mServer，并在析构时将其停止（仅当 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 ...

如果你想手动管理生命周期，也可以直接调用 controller 的相同功能：

$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://127.0.0.1:555，而不是 http://localhost: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 连接的是与单据所在账套/年份不同的账套/年份（请检查 status，并设置 companyDetail=true）
已创建 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