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

Tools

System (3)

Address Book (4)

Invoices (3)

Orders (3)

Offers (2)

Enquiries (2)

Contracts (3)

Bank Documents (2)

Cash Vouchers (2)

Internal Documents (2)

Stock / Inventory (5)

Warehouse Documents (8)

Production & Service (4)

Reports (4)

Settings (1)

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