moneys3-mcp

MCP server for Money S3 — the Czech/Slovak accounting system by Seyfor. Connects any MCP-compatible AI client to your Money S3 data via the official GraphQL API.

43 tools across 10 categories covering invoices, contacts, stock, banking, payroll, accounting, and more.

Prerequisites

Money S3 with the API module installed and configured:

1. API installed on the PC running Money S3 (selected during installation wizard)

2. API extension module purchased in Money S3

3. API Key generated: Tools → XML Data Exchange → API Keys → Add & Generate

4. App ID obtained from money.cz/navod/api-v-money-s3-pro-vyvojare

5. (Recommended) S3 Automatic task S3Api – XML import queue added for auto-processing writes

Related MCP server: SimpleShop MCP

Installation

git clone https://github.com/hlebtkachenko/moneys3-mcp.git
cd moneys3-mcp
npm install
npm run build

Configuration

Environment Variables

MCP Client Setup

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "moneys3": {
      "command": "node",
      "args": ["/absolute/path/to/moneys3-mcp/dist/index.js"],
      "env": {
        "MONEYS3_DOMAIN": "yourcompany",
        "MONEYS3_APP_ID": "your-app-id",
        "MONEYS3_CLIENT_ID": "your-client-id",
        "MONEYS3_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "moneys3": {
      "command": "node",
      "args": ["/absolute/path/to/moneys3-mcp/dist/index.js"],
      "env": {
        "MONEYS3_DOMAIN": "yourcompany",
        "MONEYS3_APP_ID": "your-app-id",
        "MONEYS3_CLIENT_ID": "your-client-id",
        "MONEYS3_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

claude mcp add moneys3 -- node /absolute/path/to/moneys3-mcp/dist/index.js

Set environment variables in your shell or .env before running.

Docker

docker build -t moneys3-mcp .
docker run -i --rm \
  -e MONEYS3_DOMAIN=yourcompany \
  -e MONEYS3_APP_ID=your-app-id \
  -e MONEYS3_CLIENT_ID=your-client-id \
  -e MONEYS3_CLIENT_SECRET=your-client-secret \
  moneys3-mcp

Generic stdio

• Command: node

• Args: ["/path/to/moneys3-mcp/dist/index.js"]

• Required env: MONEYS3_DOMAIN, MONEYS3_APP_ID, MONEYS3_CLIENT_ID, MONEYS3_CLIENT_SECRET

Quick Start

After connecting, the typical workflow is:

1. Test connection: m3_connection_test

2. List agendas: m3_agendas → pick the one you need

3. Set agenda: m3_set_agenda with the GUID

4. Query data: e.g. m3_issued_invoices, m3_stock_cards, m3_employees

If MONEYS3_AGENDA_GUID is set in env, steps 2–3 are skipped.

Available Tools

Setup (2 tools)

Invoices (5 tools)

Address Book (3 tools)

Stock & Inventory (7 tools)

Banking (5 tools)

Documents (8 tools)

Accounting (3 tools)

Payroll & HR (3 tools)

Controlling (6 tools)

Utility (3 tools)

Data Model

Money S3 operations follow two patterns:

• Reading — real-time GraphQL queries with take/skip pagination and HotChocolate-style where/order filtering

• Writing — asynchronous mutations that go into an import queue; returns a GUID to track processing status

What's Queried per Entity

Every read tool now requests the maximum useful field set inspired by the Money S3 XSD schemas:

• Invoices — full partner address, VAT summary (base + tax per rate), payment status, credit note flag, line items with discount, controlling variables (cost center / project / activity), account assignment

• Contacts — business + invoice addresses, bank accounts with IBAN/SWIFT, discount, credit limit, default maturity days, VAT payer flag, partner groups

• Banking/Cash desk — VAT summary, remaining to pay, payment date, controlling variables, line items

• Documents — VAT summary, maturity date, payment tracking, controlling variables, line items

• Stock cards — EAN/barcode, weight/volume, min/max stock, warranty, supplier, category/group, warehouse, all pricing tiers

• Stock documents — warehouse, serial numbers, discount, controlling variables

• Employees — entry/departure dates, employment type, cost center, mobile contact

• Payroll — employer social/health insurance contributions, cost center

• Accounting journal — controlling variables per entry, predefined entry reference

Filtering Examples

Invoices from a specific date:

where: { dateOfIssue: { gt: "2024-01-01" } }

Partner by company name:

where: { partnerAddress: { businessAddress: { name: { eq: "ACME s.r.o." } } } }

Sort by date descending:

order: { dateOfIssue: DESC }

Unpaid receivables:

where: { isSettled: { eq: false } }
order: { dateOfMaturity: ASC }

Architecture

src/
├── index.ts              # Entry point, env config, tool registration
├── moneys3-client.ts     # GraphQL client with OAuth2, retry, cache
├── cache.ts              # TTL-based response cache
└── tools/
    ├── helpers.ts        # escGql utility for injection prevention
    ├── agendas.ts        # Agenda selection (2)
    ├── invoices.ts       # Issued/received invoices (5)
    ├── contacts.ts       # Address book (3)
    ├── stock.ts          # Stock cards, lists, documents, inventory (7)
    ├── banking.ts        # Bank & cash desk documents (5)
    ├── documents.ts      # Internal docs, liabilities, receivables (8)
    ├── accounting.ts     # Journal, chart of accounts, entries (3)
    ├── payroll.ts        # Employees, payroll, service (3)
    ├── controlling.ts    # Cost centers, projects, activities (6)
    └── graphql.ts        # Raw GraphQL, connection test, orders (3)

Total: ~2,200 lines of TypeScript.

Security

• OAuth2 Client Credentials with automatic token refresh

• Tokens cached in memory with 60s safety margin before expiry

• All HTTP requests have 30s timeout via AbortSignal.timeout

• Rate limit handling with exponential backoff

• Automatic retry on 401 (token refresh) and 429 (rate limit)

• Actionable error messages with context-aware recovery hints

• Response caching with configurable TTL and mutation-based invalidation

• No credentials logged or exposed in error messages

• GraphQL string escaping (escGql) on all user-provided mutation parameters

• Date format validation (DD.MM.YYYY regex) on all create tools

• Raw GraphQL tool limited to 10KB query size

Tech Stack

• TypeScript, Node.js 22+

• @modelcontextprotocol/sdk for MCP protocol

• zod for input validation

• Native fetch (no HTTP library dependencies)

• GraphQL over HTTP POST (no GraphQL client library needed)

• stdio transport

Important Notes

• The GraphQL schema varies by Money S3 version. Some field names may differ in older installations. Use m3_graphql for direct schema exploration.

• Write operations are asynchronous — data goes to an import queue and is processed by S3 Automatic. The mutation returns a GUID, not immediate confirmation.

• Some delete operations fail if the document has dependent records (e.g. cannot delete a received invoice if goods were already dispatched from it).

• The API service must be running on the Money S3 PC. If requests fail with 502/503, check the S3Api Windows service.

• Questions about the API can be directed to api@money.cz.

License

MIT — see LICENSE for details.