wflow MCP Server

MCP server for wflow — Czech accounting automation platform for document management, expense tracking, approvals, storage, and organizational workflows.

78 tools across 10 categories covering the entire wflow API. OAuth2 client credentials authentication, response caching with configurable TTL, retry with exponential backoff, and actionable error messages.

Requirements

• Node.js 20+
• wflow API credentials (OAuth2 client ID and secret) — request from wflow support or create via the wflow admin panel

Installation

git clone https://github.com/hlebtkachenko/wflow-mcp.git
cd wflow-mcp
npm ci
npm run build

Docker

docker build -t wflow-mcp .
docker run -e WFLOW_CLIENT_ID=... -e WFLOW_CLIENT_SECRET=... -e WFLOW_ORGANIZATION=... wflow-mcp

Configuration

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "wflow": {
      "command": "node",
      "args": ["/absolute/path/to/wflow-mcp/dist/index.js"],
      "env": {
        "WFLOW_CLIENT_ID": "your-client-id",
        "WFLOW_CLIENT_SECRET": "your-client-secret",
        "WFLOW_ORGANIZATION": "your-org-name"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "wflow": {
      "command": "node",
      "args": ["/absolute/path/to/wflow-mcp/dist/index.js"],
      "env": {
        "WFLOW_CLIENT_ID": "your-client-id",
        "WFLOW_CLIENT_SECRET": "your-client-secret",
        "WFLOW_ORGANIZATION": "your-org-name"
      }
    }
  }
}

Claude Code

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

Set environment variables before running:

export WFLOW_CLIENT_ID=your-client-id
export WFLOW_CLIENT_SECRET=your-client-secret
export WFLOW_ORGANIZATION=your-org-name

Any MCP client (stdio)

WFLOW_CLIENT_ID=... WFLOW_CLIENT_SECRET=... WFLOW_ORGANIZATION=... node dist/index.js

Environment Variables

Variable	Required	Default	Description
WFLOW_CLIENT_ID	Yes	—	OAuth2 client ID
WFLOW_CLIENT_SECRET	Yes	—	OAuth2 client secret
WFLOW_ORGANIZATION	No	—	Default organization workspace name
WFLOW_CACHE_TTL	No	120	Cache TTL in seconds (0 to disable)
WFLOW_MAX_RETRIES	No	3	Max retries on 429 / timeout

Tools

Documents (11 tools)

Tool	Description
wf_documents	List documents with optional filtering and pagination
wf_document	Get detailed document by ID
wf_document_save	Create or update a document
wf_document_delete	Delete a document (careful!)
wf_document_with_files	Create a document with attached files
wf_document_metadata	Get or update document metadata
wf_document_lock	Lock or unlock a document
wf_document_events	Get document event history
wf_document_export	Export documents in specified format
wf_documents_queue	List documents ready for export or extraction
wf_document_task	Create or mark document task as processed

Document Files (5 tools)

Tool	Description
wf_document_files	List files attached to a document
wf_document_file_download	Download a document file
wf_document_file_upload	Upload a file to a document
wf_document_file_delete	Delete a file from a document (careful!)
wf_document_file_stamp	Apply stamp to a document file

Document Collaboration (9 tools)

Tool	Description
wf_document_approvals	Get approval status for a document
wf_document_approval_set	Set approval template on a document
wf_document_approval_clear	Remove approvals from a document (careful!)
wf_document_comments	Get comments on a document
wf_document_links	Get, add, or remove linked documents
wf_document_payments	Update payment information on a document
wf_document_rights	Get or set access rights for a document
wf_document_tags	List tags (organization-level or per document)
wf_document_tag_set	Add or remove a tag on a document

Custom Properties (10 tools)

Tool	Description
wf_doc_property_definitions	List custom property definitions for documents
wf_doc_property_definition_save	Create or update a document property definition
wf_doc_property_definition_delete	Delete a document property definition
wf_document_properties	Get or set custom properties on a document
wf_document_property_delete	Delete a custom property from a document
wf_file_property_definitions	List custom property definitions for storage files
wf_file_property_definition_save	Create or update a file property definition
wf_file_property_definition_delete	Delete a file property definition
wf_file_properties	Get or set custom properties on a storage file
wf_file_property_delete	Delete a custom property from a storage file

Storage Files (9 tools)

Tool	Description
wf_storage_files	List storage files with filtering
wf_storage_file	Get storage file details by ID
wf_storage_file_upload	Upload a file to storage
wf_storage_file_download	Download a storage file
wf_storage_file_delete	Delete a storage file (careful!)
wf_storage_file_lock	Lock or unlock a storage file
wf_storage_file_move	Move a storage file to another folder
wf_storage_file_rename	Rename a storage file
wf_storage_file_restore	Restore a deleted storage file

Storage Folders & Rights (5 tools)

Tool	Description
wf_storage_folders	List folder children or get folder by ID
wf_storage_folder_create	Create a new storage folder
wf_storage_folder_delete	Delete a storage folder (careful!)
wf_storage_file_approvals	Get, set, or clear approvals on a storage file
wf_storage_rights	Get or set access rights for a file or folder

Registers (3 tools)

Tool	Description
wf_registers	List register items by type (partners, employees, chart of accounts, etc.)
wf_register_save	Create or replace register items (full replacement)
wf_register_update	Partially update register items

Supported register types: accountingrules, activities, businesscases, businessitemcategories, businessitems, carddocumenttypes, cashdocumenttypes, cashregisters, chartofaccounts, contracts, costcenters, employees, locations, measureunits, organizationpersons, partnerpersons, partners, paymentmethods, projects, series, vatcontrolstatementlines, vatreturnlines, vatreversechargecodes, vehicles.

Organization & Access (15 tools)

Tool	Description
wf_organization	Get organization details
wf_my_organizations	List organizations available to the current user
wf_account	Get current account information
wf_users	List users in the organization
wf_user_info	Get user details by ID
wf_user_save	Create or update a user
wf_user_delete	Remove a user from the organization (careful!)
wf_roles	List all roles in the organization
wf_role_create	Create a new role
wf_role_update	Update an existing role
wf_role_delete	Delete a role (careful!)
wf_teams	List all teams in the organization
wf_team_create	Create a new team
wf_team_update	Update an existing team
wf_team_delete	Delete a team (careful!)

Configuration (12 tools)

Tool	Description
wf_document_types	List available document types
wf_document_type_save	Create or update a document type
wf_document_type_delete	Delete a document type (careful!)
wf_approval_templates	List approval templates
wf_approval_template_info	Get approval template details
wf_approval_template_save	Create or update an approval template
wf_approval_template_delete	Delete an approval template (careful!)
wf_webhooks	List webhook registrations
wf_webhook_save	Create or update a webhook registration
wf_webhook_delete	Delete a webhook registration
wf_integration_allow	Allow integration access for the organization
wf_integration_api_client	Create a new API client for integration

Raw API (1 tool)

Tool	Description
wf_api_raw	Call any wflow API endpoint directly

Response Caching

GET responses are cached in-memory with a configurable TTL (default 120 seconds). Mutations (PUT, POST, PATCH, DELETE) automatically invalidate related cache entries. Set WFLOW_CACHE_TTL=0 to disable caching.

Rate Limit Handling

When the API returns HTTP 429, the server waits using the Retry-After header value or exponential backoff, then retries automatically up to WFLOW_MAX_RETRIES times.

Security

• OAuth2 tokens are refreshed automatically and never logged
• API credentials are read from environment variables only — never stored on disk
• All API paths are validated against injection patterns (.., #)
• Error messages are truncated to 500 characters to prevent data leaks
• Zod validates every tool parameter before API calls
• Docker image runs as non-root node user
• 30-second timeout on all HTTP requests

Architecture

src/
  index.ts              — Entry point, env vars, server setup
  wflow-client.ts       — HTTP client with OAuth2, retry, caching
  cache.ts              — TTL-based in-memory response cache
  utils.ts              — textResult / errorResult MCP helpers
  types.ts              — Shared TypeScript interfaces
  tools/
    documents.ts        — Document CRUD and lifecycle (11 tools)
    document-files.ts   — Document file operations (5 tools)
    document-extras.ts  — Approvals, comments, links, rights (9 tools)
    properties.ts       — Custom property definitions and values (10 tools)
    storage.ts          — Storage files, folders, rights (14 tools)
    registers.ts        — All 24 register types (3 tools)
    organization.ts     — Org, users, roles, teams (15 tools)
    config.ts           — Doc types, approval templates, webhooks (12 tools)
    api.ts              — Raw API escape hatch (1 tool)

Tech Stack

• TypeScript 5 with strict mode
• Node.js 22 (ESM, native fetch)
• MCP SDK @modelcontextprotocol/sdk
• Zod for parameter validation
• OAuth2 client credentials flow

API Reference

• wflow API Documentation
• wflow Swagger UI
• MCP Protocol Specification

License

MIT