wflow-mcp

Community wflow MCP Server

Not affiliated with wflow. Independent open-source project, not endorsed or supported by wflow. Official MCP server: wflow AI Connect.

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

76 tools across 10 categories, checked against the official OpenAPI spec. OAuth2 client credentials authentication, response caching with configurable TTL, retries for rate limits and read timeouts, and actionable error messages.

Requirements

• Node.js 22+
• 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, 401 (token refresh) and GET timeouts
WFLOW_API_URL	No	https://api.wflow.com	API base URL (tests point it at a fake server)
WFLOW_TOKEN_URL	No	https://account.wflow.com/connect/token	OAuth2 token endpoint

Tools

Annotations: read tools are readOnlyHint; tools that delete, overwrite a whole set (rights, register, properties, payments, metadata, approvals) or have a remove/clear mode are destructiveHint; wf_api_raw is destructive and openWorldHint.

File content is not transferred over MCP except for wf_document_with_files, which takes each file base64-encoded (files[].contentBase64) and uploads it as multipart/form-data.

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 from uploaded files (PDF, ISDOC, images); wflow extracts the data. Pass each file's content base64-encoded.
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 IDs of documents ready for export or extraction (use wf_document for details)
wf_document_task	Create or mark document task as processed

Document Files (3 tools)

Tool	Description
wf_document_files	List files attached 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 all organization tags or tags on a specific 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 (7 tools)

Tool	Description
wf_storage_files	List storage files with filtering
wf_storage_file	Get storage file details by ID
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 storage 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	Add a user to the organization or update an existing one, matched by login (e-mail). roles, teams and documentTypes replace the user's current assignments when given.
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.

Retries

When the API returns HTTP 429, the server waits using the Retry-After header value or exponential backoff, then retries up to WFLOW_MAX_RETRIES times. A GET that times out is retried the same way. A write (POST, PUT, PATCH, DELETE) that times out is never repeated: the tool returns an "outcome unknown" error so the state can be checked with a read tool first.

Security

• OAuth2 tokens are refreshed automatically and never logged
• API credentials are read from environment variables only — never stored on disk
• API paths containing .. or # are rejected; organization names must match [A-Za-z0-9_-]+; IDs are validated as UUIDs
• wf_integration_api_client redacts the returned client secret
• Error details are truncated to 500 characters
• Zod validates every tool parameter before API calls
• Docker image runs as non-root node user
• 30-second timeout on all HTTP requests

Development

npm ci
npm test                # build + node:test suite against a fake wflow API
npm run check:contract  # validate every tool's request against the OpenAPI spec

Layout and design: ARCHITECTURE.md. Rules for contributors and agents: AGENTS.md.

Tech Stack

• TypeScript 7 with strict mode
• Node.js 22+ (ESM, native fetch and FormData)
• 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