reportflow-mcp

reportflow-mcp

An MCP (Model Context Protocol) server that turns your ReportFlow templates into PDF reports — invoices, contracts, statements, anything you've designed — straight from Claude, Cursor, VS Code, or any other MCP-compatible AI agent.

• Hosted remote endpoint: https://mcp.re-port-flow.com/mcp — works from Claude.ai (web) with no npm and no Node.js
• npm package: reportflow-mcp — local stdio fallback for Claude Desktop / Claude Code / Cursor / VS Code
• Source: github.com/re-port-flow/reportflow-mcp
• MCP Registry: io.github.re-port-flow/reportflow-mcp
• Smithery: smithery.ai/servers/re-port-flow/reportflow-mcp

Why ReportFlow MCP

Several MCP servers exist for business-document generation. ReportFlow MCP differentiates itself on three axes.

• Remote-ready, setup-free — The hosted endpoint at https://mcp.re-port-flow.com/mcp lets you connect from Claude.ai (web) without installing npm or Node.js. Unlike other Japanese 帳票 (chohyo) MCP servers that ship as stdio-only local processes, business users without a dev environment can start using it on day one.
• No-code template design + template marketplace — Templates are designed in a browser-based GUI editor (Konva-based) with no code. A free template gallery covers invoices, quotes, receipts, delivery slips, reports and more, so AI agents can invoke ready-made templates from day one. You don't need to author JSON schemas to add templates.
• OAuth 2.0 + Dynamic Client Registration — Authentication is OAuth 2.0 (Authorization Code + PKCE) with Dynamic Client Registration — no API key is ever handed to the AI client. The security posture matches Claude.ai's first-party Connectors.

What it does

• Generate PDFs from natural-language requests like "create an invoice for Acme Corp totalling $330"
• Expose your ReportFlow designs and their parameter schemas as MCP Resources so the AI can attach them as context
• Bulk-generate many PDFs and download them as a single ZIP
• Save outputs to your AI client's workspace folder (stdio mode only — remote mode returns download URLs)

Setup

There are two ways to connect. Remote (HTTP) is recommended because it works from Claude.ai (web) and has no install step. Use local (stdio) if you specifically want generated PDFs saved into your local workspace folder, or if you need to run without a hosted endpoint.

Remote (HTTP) — recommended

No npm, no Node.js. The MCP client opens a browser for OAuth on first connect and tokens are managed server-side.

Claude Desktop / Claude Code / Cursor

Add to .mcp.json / claude_desktop_config.json / ~/.cursor/mcp.json:

{
  "mcpServers": {
    "reportflow": {
      "type": "http",
      "url": "https://mcp.re-port-flow.com/mcp"
    }
  }
}

VS Code (MCP-enabled builds)

VS Code uses servers at the top level instead of mcpServers. Add to .vscode/mcp.json:

{
  "servers": {
    "reportflow": {
      "type": "http",
      "url": "https://mcp.re-port-flow.com/mcp"
    }
  }
}

Claude Code CLI (one-liner)

claude mcp add --transport http reportflow https://mcp.re-port-flow.com/mcp

Claude.ai (web)

Settings → Connectors → Add custom connector → paste https://mcp.re-port-flow.com/mcp. The browser opens an OAuth consent screen on first use.

Local (stdio)

Use this when you want generated PDFs saved into the AI client's workspace folder on your machine, or when you need offline-friendly distribution. Requires Node.js 18+ (auto-fetched by npx) and a local browser for first-run OAuth.

Claude Desktop / Claude Code / Cursor

{
  "mcpServers": {
    "reportflow": {
      "command": "npx",
      "args": ["-y", "reportflow-mcp"]
    }
  }
}

VS Code

{
  "servers": {
    "reportflow": {
      "command": "npx",
      "args": ["-y", "reportflow-mcp"]
    }
  }
}

Requirements

• Remote: an MCP-capable AI client (Claude.ai web, Claude Desktop, Cursor, VS Code) + a ReportFlow account. That's it.
• Local: Node.js 18+ (auto-fetched by npx) + a local environment with a browser for the first-run OAuth + a ReportFlow account.

Usage

First-run authentication

After reloading the client, ask the AI:

Authenticate with ReportFlow

In remote mode the browser opens immediately on connect. In stdio mode the AI triggers the OAuth flow on demand. Sign in → pick a workspace → consent, and you're done.

• Remote: tokens are managed server-side and refreshed automatically.
• Local: tokens are stored in the OS keychain (macOS Keychain / Windows Credential Manager / Linux libsecret), with a chmod-0600 file fallback under $XDG_STATE_HOME/reportflow-mcp/ when libsecret is unavailable.

Generate a PDF

Natural language (easiest)

Using the invoice template, create a PDF for Acme Corp totalling $330.

The AI will look up the template via list_templates, fetch its parameter schema with get_design_parameters, fill in the values, and call generate_pdf_sync — returning either a local file path (stdio) or a download URL (remote).

Slash commands

Command	Purpose
/generate_pdf	Step-by-step recipe for a single PDF
/generate_pdfs	Recipe for batch PDF generation
/reportflow_help	Quick feature tour

Where files are saved

Stdio mode, in order:

• Explicit user instruction (e.g. "save to my Desktop")
• The currently-open workspace root (Claude Code / Cursor / VS Code via MCP Roots)
• The OS temp directory as a fallback

Remote mode: the tool result contains a download URL (fileUrl) — the MCP client can't write to your filesystem directly.

Reference

Tools (called by the AI)

Every tool now carries MCP ToolAnnotations — a human-readable title plus the readOnlyHint / destructiveHint / idempotentHint / openWorldHint flags — so MCP-aware clients can render meaningful tool names and route the right approval prompts.

Tool	Title	Purpose	Annotations
authenticate	Authenticate with ReportFlow	First-time / re-auth (opens a browser)	openWorldHint: true
list_templates	List ReportFlow Templates	List available designs	readOnlyHint: true, idempotentHint: true
get_design_parameters	Get Template Parameters	Parameter schema for one design	readOnlyHint: true, idempotentHint: true
generate_pdf_sync / _async	Generate PDF (sync/async)	Generate one PDF	non-readOnly, non-destructive
generate_pdfs_sync / _async	Generate Multiple PDFs (sync/async)	Batch PDF generation, returns ZIP	non-readOnly, non-destructive
download_file (stdio only)	Download Generated File	Save an async-generated PDF to disk	idempotentHint: true
download_zip (stdio only)	Download Batch ZIP	Save the batch ZIP to disk	idempotentHint: true
suggest_params	Suggest Parameters via Sampling	Translate a NL brief into params JSON (Sampling-capable clients)	readOnlyHint: true

In remote (HTTP) mode the filesystem-writing tools (download_file, download_zip, stdio-bound generate_pdf_sync) are hidden — the remote endpoint can't reach your local disk.

Resources (attachable as AI context)

URI	Contents
reportflow://designs	List of available designs
reportflow://designs/{designId}/parameters	Parameter schema for one design
reportflow://errors	Catalog of error messages from the Content Service
reportflow://server-info	Server feature overview & version

Prompts (slash-command recipe cards)

/generate_pdf, /generate_pdfs, /reportflow_help — pass arguments and the AI follows the prepared workflow.

Troubleshooting

Symptom	Fix
Error containing re-authentication required	Ask the AI: "re-authenticate with ReportFlow"
npx cannot find the package (stdio)	npm cache clean --force then retry
No keychain available on Linux (stdio)	Falls back automatically to a chmod-0600 file under $XDG_STATE_HOME/reportflow-mcp/
Browser cannot open over SSH / remote shell (stdio)	Authenticate once on a local machine; afterwards the cached token works on remote hosts
Rate limit exceeded (429)	Per-workspace rate limit. Wait the seconds reported in the Retry-After header before retrying. Prefer async endpoints for batch jobs.

License

MIT — see LICENSE.

Links

• ReportFlow: https://re-port-flow.com
• Official docs: https://doc.re-port-flow.com/docs/integrations/mcp
• Template gallery: https://templates.re-port-flow.com
• npm: https://www.npmjs.com/package/reportflow-mcp
• Issues: https://github.com/re-port-flow/reportflow-mcp/issues