Skip to main content

Claude MCP Server

VeloxFactory shipscan anbe internaloperated directly through Claude. A dedicated MCP serverServer that— available as an add-on for VeloxFactory customers — lets Claude operate the full VeloxFactory REST API directly — listing and editingmanage report configs, managingrender connectionsdocuments, dispatch print jobs, and contexts,administer rendering reports, and dispatching print tasks,users, all through natural-languageplain requestsconversation instead of the frontend or hand-written HTTPAPI calls.

💬 In short: if you can describe the task, Claude can do it. No API documentation to read, no frontend clicks to remember.

What It Lets You Do

Source:The kiwiMCP software/mcp-server/veloxfactory/Server (kiwigives softwareClaude internalaccess projectto foldereverything VeloxFactory can do — sameorganised locationinto a few practical areas.

Manage reports by talking, not clicking. Create, update, and organise report configs, connection configs, and report contexts through conversation. "Clone the KanBan label as thea BookstackQA version and Nextcloudrename Deckthe MCPfields" servers).is Builta request Claude can carry out directly.

Render and preview on demand. Ask Claude to render any report with Node.js,real TypeScript,or example data, and get a finished PDF back — opened automatically, ready to view. No need to log into the officialfrontend or assemble an API request by hand.

Handle files without the round-trip. Uploading a new @modelcontextprotocol/sdk.jrxml, template, swapping a logo, or attaching a resource image is as simple as pointing Claude at the file on your computer. It takes care of the technical side.

Dispatch print jobs. Have Claude send a rendered document straight to a print task, check its status, or mark it as printed — the same dispatching VeloxFactory already does, just requested in a sentence.

Administer users and zodaccess. Create accounts, adjust permissions, reset passwords, or issue API tokens for schemanew validation.integrations — day-to-day administration handled conversationally.

Keep track of history. Pull up past renderings, review what was generated when and by whom, and clean up records that are no longer needed.

What itThis coversLooks Like in Practice

EveryA resourcefew examples of the /api/v1/kind APIof request the MCP Server is implementedbuilt 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:for:

  • with outputType: base64,"Render the returnedA5 PDFKanBan islabel writtenfor toarticle 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 parameters4561287-154 and show me the result"PDF."

"I designed a new label in Jaspersoft Studio — producesonboard it as a visiblereport PDFconfig." "Create a new user for our warehouse lead with admin rights." "Print this delivery note to the shop floor printer and let me know once it's done." "Show me every report config connected to the QA database."

Each of these would otherwise mean a frontend session or a small API script. With the MCP Server, they are a single message.

Who It Is For

The MCP Server is aimed at teams that already run VeloxFactory and want a faster way to handle the routine work around it — onboarding new report templates, day-to-day administration, one-off renderings, or quick checks on what has already been generated.

It is a natural fit for anyone comfortable working with Claude who would rather describe a task than click through a frontend or write an API call — including teams without anydedicated manualdeveloper downloadresources step.to spare on integration work.

Getting It

The sameMCP open/view behaviourServer is alsobuilt availableand standalonemaintained by kiwi software as an add-on to a VeloxFactory license. It runs locally alongside Claude Desktop and connects to your VeloxFactory instance using your own API credentials — nothing about your data passes through a third party.

Setup is handled together with kiwi software as part of onboarding, typically alongside the initial VeloxFactory rollout or added to an existing installation.

ℹ️ Interested? Reach out via the open_pdfGet andVeloxFactory open_urlpage, tools,or 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 eithertry the rawlive Base64demo stringfirst orat 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://demo.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:

    Build the server once (npm install && npm run build inside kiwi software/mcp-server/veloxfactory) so dist/index.js exists. Make sure .env in that folder contains a real, working VeloxFactory API token (created via Users → Token erstellen in VeloxFactory). 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. Fully restart Claude Desktop (quit, not just close the window) so it picks up the new server. 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