Skip to main content

Claude MCP Server

VeloxFactory ships an internal MCP server that lets Claude operate the full VeloxFactory REST API directly — listing and editing report configs, managing connections and contexts, rendering reports, and dispatching print tasks, all through natural-language requests instead of hand-written HTTP calls.

Source: kiwi software/mcp-server/veloxfactory/ (kiwi software internal project folder — same location as the Bookstack and Nextcloud Deck MCP servers). Built with Node.js, TypeScript, the official @modelcontextprotocol/sdk, and zod for schema validation.

What it covers

Every resource of the /api/v1/ API is implemented as a set of MCP tools:

Resource Tools
User list, get, create, update, change password, enable/disable, create/delete API token
ReportContext list, get, create, update, delete
ReportConnectionConfig list, get, create, update, delete, test connection
CommonReportResource list, get, create, update, delete
ReportConfig list, get, create, update, delete, update resources/parameters/fields, generate previews, render
ReportResource link / unlink Common Report Resource
ReportHistoryRecord list, get, create, update, delete, print, delete all linked print tasks
ReportPrintTask list, get, create, update, delete, set status, set printed
Broadcasting broadcasting/auth (included for completeness, see note below)

54 tools in total, plus two utility tools: open_pdf and open_url.

Rendering and viewing results locally

render_report_config mirrors the API's render endpoint 1:1 (outputType, parameters, data, createHistoryRecord, createPrintTask, laconicResponse, etc.) and adds one extra parameter: openResult. When set to true:

  • with outputType: base64, the returned PDF is written to a local directory (configurable via VELOXFACTORY_OUTPUT_DIR, default OS temp folder) and opened with the system's default PDF viewer.
  • with outputType: url, the returned reportUrl is opened directly in the default browser.

This means a single Claude request — "render report X with these parameters and show me the result" — produces a visible PDF without any manual download step. The same open/view behaviour is also available standalone via the open_pdf and open_url tools, e.g. to re-open a PDF fetched earlier from a History Record.

File parameters

Every endpoint that expects Base64 file content (reportFileBase64, resourceBase64, fileBase64, …) accepts either the raw Base64 string or a local filePath — the server reads and encodes the file automatically. This avoids manual Base64 round-tripping when working with local .jrxml, image, or PDF files.

Authentication & configuration

The server authenticates with a Bearer token (Laravel Sanctum), created in VeloxFactory under Users → Token erstellen, or via create_api_token. Token permissions are inherited from the owning user — a token with global:use-api plus the relevant resource :full permissions covers the full tool set.

Configuration lives entirely in a local .env file inside the project folder (not committed, see .env.example for the template), supporting either a single instance or multiple named instances:

VELOXFACTORY_INSTANCES=production
VELOXFACTORY_PRODUCTION_URL=https://veloxfactory.kiwi-software.dev
VELOXFACTORY_PRODUCTION_TOKEN=your-api-token

The server loads this file itself via dotenv, resolved relative to its own script location (not the process working directory) — so it works correctly regardless of how Claude Desktop launches the process.

Registering the server with Claude Desktop

To make the tools available in Claude, add an entry to the local Claude Desktop config file:

%APPDATA%\Claude\claude_desktop_config.json
(= C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json)

⚠️ Known pitfall: Claude Desktop's MCP launcher does not reliably honor a "cwd" field. A config using a relative args: ["dist/index.js"] plus "cwd" fails with Cannot find module 'C:\WINDOWS\System32\dist\index.js' — the process spawns with the OS default working directory (e.g. System32 on Windows) instead. The fix is to use the absolute path to dist/index.js directly in args, and drop cwd entirely:

{
  "mcpServers": {
    "veloxfactory": {
      "command": "node",
      "args": ["<absolute_path_to_your_mcp_server_instance>\\dist\\index.js"]
    }
  }
}

Replace <absolute_path_to_your_mcp_server_instance> with the full path to the project folder, e.g. C:\Users\<username>\Documents\Claude\Projekte\kiwi software\mcp-server\veloxfactory. No env block is needed — the server reads its own .env file.

Steps:

  1. Build the server once (npm install && npm run build inside kiwi software/mcp-server/veloxfactory) so dist/index.js exists.
  2. Make sure .env in that folder contains a real, working VeloxFactory API token (created via Users → Token erstellen in VeloxFactory).
  3. Open claude_desktop_config.json, add the veloxfactory block into the existing mcpServers object (alongside bookstack and nextcloud-deck, do not overwrite them), with the absolute path to dist/index.js in args.
  4. Fully restart Claude Desktop (quit, not just close the window) so it picks up the new server.
  5. Verify: ask Claude to list report configs — if the tool answers, the server is wired up correctly. Check the MCP server log in Claude Desktop if it doesn't.

A ready-to-copy version of this block (with the real local path already filled in) also lives in claude_mcp_config.json inside the project folder.

What's intentionally out of scope

No WebSocket/Reverb client is implemented. Real-time print task updates (private-report-print-tasks channel) are only relevant to the C#-based print service, not to an MCP server driven by Claude. The broadcasting/auth endpoint is still exposed as a tool for full API coverage, but VeloxFactory's own API docs already note it "should not normally be called manually" — without a WebSocket client behind it, it has no practical standalone use here.

There is no dedicated Claude Skill on top of the MCP server yet. The tool descriptions carry enough context (parameter docs, enum values, required-field notes) for Claude to operate the API correctly on its own. A skill encoding common multi-step workflows (e.g. "render and print in one go", "onboard a new report config from a .jrxml file") can be added later if needed.

Build & run

cd kiwi software/mcp-server/veloxfactory
npm install
npm run build      # tsc -> dist/
node dist/index.js

Reference docs used while building this: Meet the API, Meet the frontend (permissions model), Rendering with our powerful API.

Back to top