POHODA MCP Server

MCP server for POHODA (Stormware) accounting software. Manage invoices, stock, orders, bank documents, warehouse, and accounting from any MCP-compatible client.

48 tools covering all major POHODA agendas via mServer XML API.

Requirements

• Node.js 20+
• POHODA with mServer enabled and running
• mServer user credentials with XML communication rights

Installation

git clone https://github.com/hlebtkachenko/pohoda-mcp.git
cd pohoda-mcp
npm ci
npm run build

Configuration

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "pohoda": {
      "command": "node",
      "args": ["/path/to/pohoda-mcp/dist/index.js"],
      "env": {
        "POHODA_URL": "http://localhost:444",
        "POHODA_USERNAME": "<your-username>",
        "POHODA_PASSWORD": "<your-password>",
        "POHODA_ICO": "<your-company-ico>"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json (location)

{
  "mcpServers": {
    "pohoda": {
      "command": "node",
      "args": ["/path/to/pohoda-mcp/dist/index.js"],
      "env": {
        "POHODA_URL": "http://localhost:444",
        "POHODA_USERNAME": "<your-username>",
        "POHODA_PASSWORD": "<your-password>",
        "POHODA_ICO": "<your-company-ico>"
      }
    }
  }
}

Claude Code

.mcp.json in your project root, or ~/.claude.json globally:

{
  "mcpServers": {
    "pohoda": {
      "command": "node",
      "args": ["/path/to/pohoda-mcp/dist/index.js"],
      "env": {
        "POHODA_URL": "http://localhost:444",
        "POHODA_USERNAME": "<your-username>",
        "POHODA_PASSWORD": "<your-password>",
        "POHODA_ICO": "<your-company-ico>"
      }
    }
  }
}

Any MCP client (stdio)

The server uses stdio transport. Point your MCP client to:

node /path/to/pohoda-mcp/dist/index.js

With environment variables set for authentication (see below).

Environment Variables

Variable	Required	Description
POHODA_URL	Yes	mServer URL (default port: 444)
POHODA_USERNAME	Yes	POHODA user with XML rights
POHODA_PASSWORD	Yes	POHODA password
POHODA_ICO	Yes	Company IČO (accounting unit)
POHODA_TIMEOUT	No	Request timeout in ms (default: 120000)
POHODA_MAX_RETRIES	No	Max retries on timeout/503 (default: 2)
POHODA_CHECK_DUPLICITY	No	Enable duplicate import checks (default: false)

Tools

System (3)

Tool	Description
pohoda_status	Check mServer status (processing queue, idle/working)
pohoda_company_info	Get accounting unit info (company name, database, period)
pohoda_download_file	Download a file from POHODA's documents folder

Address Book (4)

Tool	Description
pohoda_list_addresses	Export contacts with filters (name, IČO, code, date)
pohoda_create_address	Create a new contact in address book
pohoda_update_address	Update an existing contact by ID
pohoda_delete_address	Delete a contact by ID

Invoices (3)

Tool	Description
pohoda_list_invoices	Export invoices — issued, received, advance, credit notes, receivables, commitments
pohoda_create_invoice	Create an invoice with line items, partner, symbols, VAT
pohoda_delete_invoice	Delete an invoice by ID

Orders (3)

Tool	Description
pohoda_list_orders	Export issued/received orders with filters
pohoda_create_order	Create an order with items and partner
pohoda_delete_order	Delete an order by ID

Offers (2)

Tool	Description
pohoda_list_offers	Export issued/received offers
pohoda_create_offer	Create an offer with items

Enquiries (2)

Tool	Description
pohoda_list_enquiries	Export issued/received enquiries
pohoda_create_enquiry	Create an enquiry with items

Contracts (3)

Tool	Description
pohoda_list_contracts	Export contracts with filters
pohoda_create_contract	Create a new contract
pohoda_delete_contract	Delete a contract by ID

Bank Documents (2)

Tool	Description
pohoda_list_bank	Export bank documents (receipts/expenses)
pohoda_create_bank	Create a bank document with items

Cash Vouchers (2)

Tool	Description
pohoda_list_vouchers	Export cash register vouchers
pohoda_create_voucher	Create a cash voucher (receipt/expense)

Internal Documents (2)

Tool	Description
pohoda_list_internal_docs	Export internal accounting documents
pohoda_create_internal_doc	Create an internal document

Stock / Inventory (5)

Tool	Description
pohoda_list_stock	Export stock items with filters (code, name, store)
pohoda_create_stock	Create a new stock item
pohoda_update_stock	Update a stock item by ID or code
pohoda_delete_stock	Delete a stock item
pohoda_list_stores	List all stores (warehouses)

Warehouse Documents (8)

Tool	Description
pohoda_list_prijemky	Export receiving documents (příjemky)
pohoda_create_prijemka	Create a receiving document
pohoda_list_vydejky	Export dispatch documents (výdejky)
pohoda_create_vydejka	Create a dispatch document
pohoda_list_prodejky	Export sales documents (prodejky)
pohoda_create_prodejka	Create a sales document
pohoda_list_prevodky	Export transfer documents (převodky)
pohoda_create_prevodka	Create a transfer document

Production & Service (4)

Tool	Description
pohoda_list_vyroba	Export production documents
pohoda_create_vyroba	Create a production document
pohoda_list_service	Export service records
pohoda_create_service	Create a service record

Reports (4)

Tool	Description
pohoda_list_accountancy	Export accounting journal entries
pohoda_list_balance	Export saldo/balance records
pohoda_list_movements	Export stock movement records
pohoda_list_vat	Export VAT classification records

Settings (1)

Tool	Description
pohoda_list_settings	Export settings (numerical series, bank accounts, cash registers, centres, activities, payment methods, stores, storage, categories, accounting units)

Docker

docker build -t pohoda-mcp .
docker run --rm -i \
  -e POHODA_URL=http://host.docker.internal:444 \
  -e POHODA_USERNAME=<your-username> \
  -e POHODA_PASSWORD=<your-password> \
  -e POHODA_ICO=<your-company-ico> \
  pohoda-mcp

Multi-stage build, runs as non-root node user.

Security

• Credentials via environment variables only
• STW-Authorization Basic auth per POHODA mServer specification
• STW-Application: pohoda-mcp header for audit trail in POHODA monitoring
• STW-Check-Duplicity header support to prevent duplicate imports
• XML escaping handled by xmlbuilder2 for all user-provided values
• Path traversal prevention for file downloads (normalize + reject .. prefixed paths)
• Input validation via Zod on all tool parameters

Architecture

src/
  index.ts              Entry point, env validation, tool registration
  client.ts             HTTP client (STW-Auth, Windows-1250, gzip/deflate, retries)
  xml/
    builder.ts          DataPack XML envelope builder (xmlbuilder2)
    parser.ts           ResponsePack parser (fast-xml-parser)
    namespaces.ts       40+ POHODA XML namespace URIs
  core/
    types.ts            ToolResult interface, ok/err helpers
    shared.ts           Date conversion, env helpers
    filters.ts          Filter builder for export requests
  tools/
    system.ts           Status, company info, file download (3 tools)
    addresses.ts        Address book CRUD (4 tools)
    invoices.ts         All invoice types (3 tools)
    orders.ts           Issued/received orders (3 tools)
    offers.ts           Offers (2 tools)
    enquiries.ts        Enquiries (2 tools)
    contracts.ts        Contracts (3 tools)
    bank.ts             Bank documents (2 tools)
    vouchers.ts         Cash vouchers (2 tools)
    internal_docs.ts    Internal documents (2 tools)
    stock.ts            Stock/inventory CRUD (5 tools)
    warehouse.ts        Příjemky, výdejky, prodejky, převodky (8 tools)
    production.ts       Production and service records (4 tools)
    reports.ts          Accountancy, balance, movements, VAT (4 tools)
    settings.ts         Numerical series, bank accounts, centres... (1 tool)

POHODA mServer Setup

1. Open POHODA → Settings → mServer
2. Create a new mServer configuration
3. Set the listening port (default: 444)
4. Start the mServer
5. Ensure the user has XML communication rights (Settings → Access Rights → File → Data Communication)

For internet access, use HTTPS or VPN. mServer is primarily designed for local network use.

Tech Stack

• TypeScript
• @modelcontextprotocol/sdk
• Zod (schema validation)
• xmlbuilder2 (XML generation)
• fast-xml-parser (XML parsing)
• iconv-lite (Windows-1250 encoding)
• Native fetch

API Reference

• POHODA XML Documentation
• POHODA Developer Guide

License

MIT