Pohoda MCP

Servidor MCP para el software de contabilidad Pohoda (checo) - leer y crear facturas, pedidos, inventario, contactos a través de la API XML de mServer.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor Pohoda MCP

Servidor MCP para el software contable Pohoda de Stormware. Se comunica con Pohoda a través de mServer XML API.

Conecta a tu asistente de IA directamente con la contabilidad. Pregunta por facturas, navega por el directorio, controla el inventario, crea nuevos documentos o haz que se imprima una factura en PDF. Solo tienes que escribir lo que necesitas y el servidor MCP se encargará de la comunicación con Pohoda.

Requisitos

PHP 8.1+
ext-curl, ext-dom, ext-simplexml
Pohoda con mServer activo (esquema versión 2)

Configuración de mServer en Pohoda

Antes de usar el servidor MCP, es necesario activar y configurar mServer en Pohoda.

1. Apertura de la administración de mServer

En el programa Pohoda, abre la agenda Unidades contables, en el menú elige Base de datos > POHODA mServer.

2. Administración de configuraciones

Se abre un cuadro de diálogo con la lista de configuraciones de mServer. Para cada configuración se indica el nombre, puerto, estado de ejecución, host y PID.

3. Creación de una nueva instancia

Haz clic en Nuevo y en la pestaña Básico configura:

Nombre del mServer
Unidad contable con la que se comunicará el mServer
Puerto para la comunicación (por defecto 444)

En la pestaña HTTPS se puede activar la comunicación segura:

En la pestaña Monitoreo se puede activar el registro de comunicación:

4. Inicio

Selecciona la configuración y haz clic en Iniciar (o haz doble clic en el registro). mServer comenzará a escuchar en el puerto configurado.

Alternativamente, se puede controlar mServer desde la línea de comandos usando el interruptor /HTTP sobre pohoda.exe. Como último parámetro se indica el nombre de la configuración (entre comillas si contiene espacios):

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

Otros comandos: stop /f (terminación forzada), list:xml (listado de configuraciones en XML). Para el inicio automático al arrancar el sistema, Stormware recomienda el Programador de tareas de Windows (no el servicio de Windows).

Detalles en documentación de Stormware.

Instalación del servidor MCP

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

Configuración

El servidor se configura mediante variables de entorno:

Variable	Descripción	Por defecto
`POHODA_URL`	URL de mServer	`http://localhost:444`
`POHODA_ICO`	ICO de la unidad contable
`POHODA_USERNAME`	Nombre de usuario para mServer
`POHODA_PASSWORD`	Contraseña
`POHODA_EXE_PATH`	Ruta a `Pohoda.exe` para el inicio automático de mServer (opcional)
`POHODA_CONFIG_NAME`	Nombre de la configuración de mServer para el inicio automático (opcional)

Si se configuran POHODA_EXE_PATH y POHODA_CONFIG_NAME, el servidor antes de la primera llamada a herramienta verificará que mServer esté en ejecución; si no, lo iniciará él mismo mediante pohoda.exe /HTTP start. Al finalizar el servidor MCP, lo detendrá de nuevo, pero solo si él mismo lo inició (si mServer ya estaba en ejecución, lo dejamos correr). Solo Windows (mServer es parte de Pohoda).

Uso en agentes (p. ej., Claude Code)

Agrégalo a .mcp.json o a la configuración del proyecto:

{
    "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"
            }
        }
    }
}

Las dos últimas variables son opcionales: sirven para el inicio automático de mServer en la primera llamada a herramienta (ver arriba).

Herramientas disponibles

status

Verifica si mServer está en ejecución y responde. La llamada básica devuelve solo un texto breve de GET /status (Pohoda responde con una cadena simple, no XML). Con el parámetro companyDetail=true, además, mediante una consulta autenticada devuelve el nombre de la unidad contable, el nombre de la base de datos y el año contable actual.

Parámetro	Descripción
`companyDetail`	`true` / `false` — devolver también datos sobre la unidad contable activa (por defecto `false`)

list_documents, list_stock, list_contacts

Tres herramientas de lectura divididas según el tipo de registro. Las agendas de nicho/listas (centre, activity, store, bankAccount, cashRegister, numericalSeries) no están disponibles a través de una herramienta dedicada; usa raw_xml.

list_documents

Documentos. Parámetro agenda — uno de los siguientes:

Agenda	Descripción	Agenda	Descripción
`invoice`	facturas*	`prijemka`	entradas
`order`	pedidos	`vydejka`	salidas
`voucher`	documentos de caja	`prodejka`	ventas
`bank`	banco	`prevodka`	transferencias
`contract`	trabajos	`vyroba`	producción
`intDoc`	documentos internos	`accountancy`	diario contable
`offer`	ofertas
`enquiry`	solicitudes

* La agenda invoice requiere el parámetro invoiceType: issuedInvoice o receivedInvoice.

Filtros: id, dateFrom, dateTill, company, ico, number (coincidencia exacta del valor completo, no subcadena), lastChanges (registros modificados desde YYYY-MM-DDThh:mm:ss), limit (por defecto 100, recorte del cliente).

list_stock

Inventario. Filtros: id, code, name, EAN, storage (ruta en la estructura del almacén, p. ej. "ZBOZI/Elektro"), store (abreviatura del almacén), internet (true/false), lastChanges, limit.

list_contacts

Directorio. Filtros: id, company, ico, lastChanges, limit.

create_invoice

Creación de factura emitida o recibida. Admite:

dirección del socio directamente o vínculo al directorio (partnerId)
símbolo variable, fecha de vencimiento, fecha del hecho imponible
precontabilización, método de pago, cuenta bancaria
centro, actividad, trabajo
moneda extranjera con tipo de cambio
artículos con vínculo a la tarjeta de almacén (stockCode)

create_address

Creación de un registro en el directorio (empresa/contacto).

create_stock

Creación de una tarjeta de almacén. Además de los datos básicos (código, nombre, precio), admite:

EAN, PLU para cajas registradoras
indicadores para venta y tienda en línea
descripción, complemento del nombre, nombre corto
stock mínimo y máximo, peso
proveedor, garantía

create_order

Creación de un pedido recibido o emitido con artículos.

print

Impresión o exportación a PDF de cualquier registro. Puede:

imprimir en impresora (predeterminada o específica)
exportar a archivo PDF en el servidor (pdfPath es obligatorio para la ruta del PDF)
devolver el PDF como Base64 directamente en la respuesta (pdfBase64=true, requiere pdfPath)

La agenda se especifica en checo: vydane_faktury, prijate_faktury, zasoby, adresar, pokladna, banka, interni_doklady, zakazky, vydejky, prijemky, prodejky, vydane_objednavky, prijate_objednavky, vydane_nabidky, prijate_nabidky, etc.

El ID del informe de impresión (reportId) varía según la instalación y las modificaciones propias. En Pohoda lo puedes encontrar en el Editor de informes de impresión (menú Archivo → Informes de impresión), donde en cada informe ves la columna ID, o mediante el botón derecho del ratón sobre el informe en el diálogo de impresión → Propiedades. Los informes estándar suministrados tienen ID en el orden de cientos a miles (típicamente 200–3000+).

raw_xml

Envío de cualquier XML. Cubre los casos que las demás herramientas no alcanzan. El XML se inserta directamente en el sobre <dat:dataPackItem>, por lo que debe contener sus propias declaraciones de namespace.

Recursos de referencia (recursos MCP)

Los catálogos de valores permitidos se exponen como recursos MCP, de modo que el cliente puede obtenerlos sin llamada a herramienta:

URI	Contenido
`pohoda://enums/agendas`	lista de agendas dividida según qué herramienta de lista la cubre
`pohoda://enums/vat-rates`	valores permitidos de `vatRate` en artículos (`none`, `low`, `high`)
`pohoda://enums/payment-types`	valores de `paymentType` de facturas (`draft`, `cash`, `card`, `compensation`)
`pohoda://enums/print-agendas`	nombres checos de agendas aceptados por `print`

Uso desde código PHP (sin MCP)

La biblioteca también se puede usar directamente como cliente PHP para mServer, independientemente de MCP. Es útil para scripts propios, trabajos cron o integración en una aplicación existente.

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

Métodos públicos de PohodaClient: getStatus(), listRecords(), createInvoice(), createAddress(), createStock(), createOrder(), printRecord(), sendRawXml().

Inicio y detención de mServer

Si el script no puede asumir que mServer ya está en ejecución, la clase MServerController es útil. Es un envoltorio delgado sobre pohoda.exe /HTTP start|stop que inicia Pohoda de forma no bloqueante y después del inicio consulta PohodaClient::getStatus() hasta que mServer comienza a responder. Solo Windows.

La forma más sencilla es pasarlo a PohodaClient — este entonces iniciará mServer de forma diferida antes de la primera solicitud HTTP y al destruirse lo detendrá de nuevo (solo si él mismo lo inició; si ya estaba en ejecución, lo dejamos correr):

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

Si quieres gestionar el ciclo de vida manualmente, el controlador puede hacer lo mismo directamente:

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

Al llamar a los endpoints HTTP, usa http://127.0.0.1:555, no http://localhost:555 — el resolver de PHP intenta para localhost primero IPv6 (::1), donde mServer no escucha, y se espera innecesariamente hasta el tiempo de espera.

Métodos públicos de MServerController:

start(PohodaClient $client, int $timeoutSeconds = 30) — inicia Pohoda con /HTTP start, espera hasta que el estado HTTP de la API responda. En caso de tiempo de espera, lanza RuntimeException.
stop() — envía /HTTP stop de tipo fire-and-forget, no espera la finalización.

Solución de problemas

Síntoma	Causa probable
`Curl Error: Connection refused`	mServer no está en ejecución; inícialo en Pohoda o mediante `pohoda.exe /HTTP start`
`HTTP 401`	`POHODA_USERNAME` / `POHODA_PASSWORD` incorrectos
La respuesta es HTML con página de inicio de sesión	El usuario en Pohoda no tiene permisos para mServer o la agenda está abierta por otra instancia
`state="error"` + `note="Nepodařila se validace dokumentu podle schématu"`	Estructura XML incorrecta — típicamente namespace intercambiado o elemento obligatorio faltante; el texto del error señala el elemento
`listRecords` devuelve lista vacía	mServer está conectado a una unidad contable/año diferente de donde vive el documento (verifica `status` con `companyDetail=true`)
`pdfPath` se crea pero no se puede abrir (0 B)	mServer no tiene permisos para escribir en ese lugar — prueba el `D:\Data\ucto\Tisk\` predeterminado o el directorio temporal del usuario bajo el que se ejecuta Pohoda
`Print` devuelve OK, pero el PDF no se genera	`reportId` no existe en la instalación; verifica el ID en el Editor de informes de impresión

Estructura del proyecto

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