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 in .env (see .env.example in the project folder), supporting either a single instance or multiple named instances (e.g. production + a demo system):

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

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)

Merge the following into the existing "mcpServers" object (alongside bookstack and nextcloud-deck, do not overwrite them):

{
  "mcpServers": {
    "veloxfactory": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "<path_to_your_mcp_server_instance>"
    }
  }
}

Steps:

  1. Build the server once (npm install && npm run build inside kiwi software/mcp-server/veloxfactory) so dist/index.js exists.
  2. Create a real API token in VeloxFactory (Users → Token erstellen) and paste it into VELOXFACTORY_PRODUCTION_TOKEN above — both in the config entry and in the project's local .env.
  3. Open claude_desktop_config.json, add the veloxfactory block into the existing mcpServers object.
  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.

A ready-to-copy version of this block (with a placeholder path) 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