Skip to main content
Glama

wflow-mcp — experimental MCP server for the wflow.com public API

⚠️ Experimental / proof of concept. Not an official wflow product. Built to explore what Claude can do over the wflow public API. Use against a test/playground organization.

📚 A full offline reference of the wflow public API (all 173 operations + schemas) is bundled at docs/wflow-public-api.md.

A Model Context Protocol server that lets Claude (Desktop, Code, or any MCP client) operate the wflow.com document platform through its public API — read and change documents, registers (cost centres, contracts, …), users, roles and teams, across one or many organizations.

It is built to cover the use cases from the "Využití Claude s wflow API" deck plus the long tail of the API, and it does auth, organization routing, pagination and rate-limit handling for you.


What it can do (mapped to the deck)

Slide

Example ask

Tools that serve it

Users / roles / teams across orgs

"Which users can pay across organizations?"

wflow_find_users_with_right (cross-org, defaults to payment rights)

"Replace user Y with X in all organizations"

wflow_list_users (allOrganizations) → wflow_upsert_user / wflow_delete_user per org

"Create team X and add these users"

wflow_list_users → wflow_upsert_team

"Prepare re-invoicing docs for client access"

wflow_list_users + wflow_get_user (roles/teams/rights) across orgs

Bulk document changes

"Set all documents with order Z01 to cost centre Centrála"

wflow_get_register (resolve the code) → wflow_bulk_update_documents

"Import line items from this table into this invoice"

wflow_update_document (lines: [...])

"Find documents for these transactions across all orgs"

wflow_search_documents (allOrganizations, query)

Controlling / reporting

"Find inconsistencies in posting"

wflow_search_documents + wflow_get_document / wflow_get_document_events

"Is any cost centre inactive this quarter?"

wflow_get_register + wflow_search_documents

"Find deviations vs. the ledger export"

wflow_export_documents (datev/excel/…)

"Where is the order for this invoice?"

wflow_search_documents (query=orderNo = "…")

Anything not covered by a typed tool is reachable via wflow_request (browse the full surface with wflow_api_catalog) — so the server exposes all 173 API operations.


Related MCP server: OpenText Process Automation MCP

Tools (26)

Discovery & generic

  • wflow_list_organizations — orgs the principal can access (foundation for cross-org work)

  • wflow_whoami — current account/identity for an org

  • wflow_api_catalog — browse/filter the full endpoint catalog

  • wflow_request — call any endpoint (method, path, org, query, body)

Documents

  • wflow_search_documents — filter/sort/auto-paginate, single or cross-org

  • wflow_get_document · wflow_get_document_events

  • wflow_update_document — create/update; set accounting registers by code, add line items

  • wflow_bulk_update_documents — query → patch every match (dry-run by default)

  • wflow_export_documents — export to ERP/accounting formats (datev, excel, isdoc, money…)

  • wflow_upload_document_file · wflow_create_document_with_files

Registers (cost centres, contracts, activities, chart of accounts, partners, projects, …)

  • wflow_get_register · wflow_upsert_register (PUT = replace set / PATCH = partial)

Users / roles / teams

  • wflow_list_users · wflow_get_user · wflow_upsert_user · wflow_delete_user

  • wflow_find_users_with_right — cross-org "who can do X" (e.g. who can pay)

  • wflow_list_roles · wflow_upsert_role · wflow_delete_role

  • wflow_list_teams · wflow_get_team · wflow_upsert_team · wflow_delete_team


Setup

cd wflow-mcp
npm install
npm run build
cp .env.example .env   # then edit .env

Configure .env

WFLOW_AUTH_MODE=client_credentials
WFLOW_ORG=your-org-slug
WFLOW_CLIENT_ID=your_client_id
WFLOW_CLIENT_SECRET=…
WFLOW_READONLY=false          # set true to block all writes
WFLOW_MAX_ITEMS=2000          # auto-pagination safety cap per org

Verify it works (live smoke test)

npm run smoke

This spawns the server over stdio exactly like a Claude client, lists the tools, does a set of reads, then creates → bulk-updates → verifies → deletes a throwaway document.


Authentication

Two OAuth 2.0 flows, selected by WFLOW_AUTH_MODE:

1. client_credentials (default, machine-to-machine)

Uses WFLOW_CLIENT_ID + WFLOW_CLIENT_SECRET, scope uccl_common_api. The client must be granted access to each organization in wflow → Settings → Integrations → API accesses. This is what the provided _docasny client uses and it works out of the box.

2. interactive (opens the wflow login page — you type your username/password)

Authorization Code + PKCE. Set WFLOW_AUTH_MODE=interactive and WFLOW_CLIENT_ID, then:

npm run login   # opens https://account.wflow.com in your browser

The refresh token is cached in ~/.wflow-mcp/tokens.json, so the server starts without prompting afterwards. With interactive auth, wflow_list_organizations returns every org your account can see — which is what makes the cross-organization use cases shine.

Requirement: the client must be registered in wflow with grant type Authorization code and must whitelist the redirect URI http://localhost:53682/callback. Interactive clients are set up via wflow technical support. The provided _docasny client is client-credentials only, so interactive mode needs a separate interactive client id.


Add to Claude

Claude Desktop / Claude Code (.mcp.json or claude_desktop_config.json)

{
  "mcpServers": {
    "wflow": {
      "command": "node",
      "args": ["/absolute/path/to/wflow-mcp/dist/index.js"],
      "env": {
        "WFLOW_AUTH_MODE": "client_credentials",
        "WFLOW_ORG": "your-org-slug",
        "WFLOW_CLIENT_ID": "your_client_id",
        "WFLOW_CLIENT_SECRET": "PUT-SECRET-HERE",
        "WFLOW_READONLY": "false"
      }
    }
  }
}

(Environment variables set here override .env, and don't depend on the working directory.)

Claude Code (CLI, one-liner)

claude mcp add wflow \
  -e WFLOW_AUTH_MODE=client_credentials \
  -e WFLOW_ORG=your-org-slug \
  -e WFLOW_CLIENT_ID=your_client_id \
  -e WFLOW_CLIENT_SECRET=PUT-SECRET-HERE \
  -- node /absolute/path/to/wflow-mcp/dist/index.js

Then in Claude: "List my wflow organizations", "Which users can pay?", "Set every document with order Z01 to cost centre 123 (dry run first)".


Design notes & safety

  • Hybrid tool surface. High-value typed tools for the deck's workflows + a generic wflow_request for the entire API. The endpoint catalog (src/endpoints.json, 173 ops) is bundled so wflow_api_catalog works offline.

  • Cross-org is first-class. search, list_users, list_teams, find_users_with_right and bulk_update accept organizations: [...] or allOrganizations: true and fan out.

  • Registers by code. Set accounting.costCenter = {code:"123"} (or externalId/id); wflow resolves the register on write — no id lookup needed. (Assigning an invalid register code is silently ignored by wflow.)

  • Dry-run by default. wflow_bulk_update_documents previews matches unless apply=true.

  • Read-only mode. WFLOW_READONLY=true blocks every non-GET request.

  • Pagination. List/search auto-paginate up to WFLOW_MAX_ITEMS per org and report truncated.

  • Rate limits. 429s are retried once, respecting x-rate-limit-period.

Project layout

src/
  config.ts        env + .env loader
  auth.ts          token manager (client_credentials + interactive PKCE)
  client.ts        HTTP client, org resolution, pagination
  util.ts          result helpers + endpoint catalog loader
  endpoints.json   bundled catalog of all 173 API operations
  tools/
    discovery.ts   list_organizations, whoami, api_catalog, request
    documents.ts   search, get, update, bulk_update, events, export, upload, create_with_files
    registers.ts   get_register, upsert_register
    people.ts      users, roles, teams, find_users_with_right
  index.ts         server bootstrap (stdio)
  login.ts         standalone interactive login (npm run login)
scripts/smoke.ts   end-to-end test against the live playground

Available Tools

26 tools
wflow_api_catalogBrowse the wflow API catalogA

Return the catalog of wflow public API operations (method, path, summary, tag). Use this to discover endpoints that no typed tool covers, then call them with wflow_request. Optionally filter by a keyword or tag (e.g. 'payment', 'approval', 'storage', 'partner').

Inputs: filter.

wflow_bulk_update_documentsBulk-update documents matching a filterA

Find every document matching a wflow query (optionally across organizations) and apply the SAME partial patch to each. This powers requests like 'set all documents with order Z01 to cost centre Centrála'. SAFETY: runs as a DRY RUN by default (apply=false) — it returns the matched documents and the patch that would be applied, but changes nothing. Re-run with apply=true to execute. patch is a partial DocumentUpdate merged with each document's id, e.g. {accounting:{costCenter:{code:"CENTRALA"}}}.

Inputs: patch (required), query (required), apply, maxItems, +4 more.

wflow_create_document_with_filesCreate a document from uploaded filesA

Create a new document and attach one or more local files in a single call (SK QR receipts and ISDOC files are auto-extracted). Optionally pin a document typeId and invoiceType.

Inputs: filePaths (required), typeId, invoiceType, organization.

wflow_delete_roleDelete a roleB

Delete a role by id. Irreversible.

Inputs: roleId (required), organization.

wflow_delete_teamDelete a teamA

Delete a team by id. Irreversible.

Inputs: teamId (required), organization.

wflow_delete_userRemove a user from an organizationB

Delete (revoke) a user from an organization by id. Irreversible — confirm intent before calling.

Inputs: userId (required), organization.

wflow_export_documentsExport documents to an ERP/accounting formatA

Export a set of documents in a given format (byznyssolitea, datev, excel, generic, isdoc, kros, moneyerp, moneys3, mrp, premier, xml). Optionally narrow the set with a StructuredFilter filter (search/sort/filters). The exported file is written to disk and its path returned (useful for 'compare against the accounting ledger export').

Inputs: format (required), filter, savePath, parameters, +2 more.

wflow_find_users_with_rightFind users holding a right (e.g. who can pay) — cross-organizationA

Sweep organizations and return every user who holds a given right, or full-access users (who implicitly have all rights). Defaults to payment rights (CanMarkForPayment, CanManagePayments), directly answering 'which users can pay across organizations?'. Pass rights to check other rights (e.g. CanExport, CanApprove, CanManageSettings).

Inputs: rights, organization, organizations, allOrganizations, +1 more.

wflow_get_documentGet a document by idA

Fetch the full document object (all fields, VAT subtotals, lines, accounting) by its id.

Inputs: documentId (required), organization.

wflow_get_document_eventsGet document event historyA

Return the chronological event/audit trail for a document (created, updated, approved, changed accounting, exported, …). Useful for controlling and spotting inconsistencies.

Inputs: documentId (required), organization.

wflow_get_registerRead a register (cost centres, contracts, partners, …)A

Read entries from any wflow register/reference table. type is one of: accountingrules, activities, businesscases, businessitems, businessitemcategories, carddocumenttypes, cashdocumenttypes, cashregisters, chartofaccounts, contracts, costcenters, employees, locations, measureunits, organizationpersons, partnerpersons, partners, paymentmethods, projects, series, vatcontrolstatementlines, vatreturnlines, vatreversechargecodes, vehicles. Each entry typically has {id, externalId, code, description, isValid}. Supports the wflow query/sort syntax and auto-pagination — e.g. resolve a cost centre named 'Centrála' with type='costcenters' and query=description = "Centrála".

Inputs: type (required), sort, query, maxItems, +2 more.

wflow_get_teamGet a team (with members)A

Fetch a team by id including its member users.

Inputs: teamId (required), organization.

wflow_get_userGet a user (full: roles, teams, rights)A

Fetch a user by id including role & team membership, document-type permissions and effective rights (UserFull).

Inputs: userId (required), organization.

wflow_list_organizationsList organizationsA

List all wflow organizations the authenticated principal can access. Returns name, baseURL and slug (subdomain). The slug is what every other tool uses as organization. This is the entry point for any cross-organization task.

Inputs: no named parameters.

wflow_list_rolesList rolesA

List roles in an organization (id, name, description). Get one role's rights & members via wflow_request GET roles/{id}.

Inputs: search, organization.

wflow_list_teamsList teams (cross-organization)A

List teams in one or many organizations (id, name, description, system flag).

Inputs: search, organization, organizations, allOrganizations.

wflow_list_usersList users (cross-organization)A

List users in one or many organizations. Each user has {id, identity:{login, fullName}, hasFullAccess}. Use allOrganizations to sweep every org (e.g. to find where a user exists).

Inputs: query, search, maxItems, organization, +2 more.

wflow_requestCall any wflow API endpoint (generic)A

Low-level escape hatch to call ANY wflow public API endpoint. Use this when no typed tool fits (browse the surface with wflow_api_catalog first). • path may be a bare resource ('documents', 'registers/costcenters'), an org-templated path ('/api/{organization}/roles') or the org is injected automatically for relative paths. • {organization} in the path (or a relative path) is filled from the organization argument or WFLOW_ORG. • query is an object of query-string parameters (wflow filter syntax for query, e.g. totalAmount > 1000). • body is sent as JSON for PUT/POST/PATCH. Writes (non-GET) are blocked when WFLOW_READONLY is set.

Inputs: path (required), body, query, method, +1 more.

wflow_search_documentsSearch documents (filter/sort, cross-organization)A

Search / list documents across one or many organizations with the wflow filter syntax and auto-pagination. • query uses wflow filtering, e.g. orderNo = "Z01", totalAmount > 1000 and totalAmount < 5000, created > "2026-01-01", number = null. Quote the field name-free value as shown. • sort is a comma list, e.g. created desc,totalAmount. • Set allOrganizations or organizations for cross-org queries (e.g. 'find documents for these transactions across all organizations'). Returns slim rows by default; set slim=false for full document objects.

Inputs: slim, sort, query, maxItems, +3 more.

wflow_update_documentAdd or update a documentA

Create (omit id) or update (include id) a document. Only the fields you send are changed — unspecified fields are left untouched. Registers (costCenter, contract, activity, accountingRule, project, …) are set under accounting and may be referenced by {code}, {externalId} or {id} — wflow resolves them on write. Example accounting: {accounting:{costCenter:{code:"202"}, contract:{code:"12345"}}}. Line items go in lines (array of {description, quantity, unitPrice, totalAmount, vatRate, costCenter, …}).

Inputs: document (required), ignoreLock, setAsFilled, organization.

wflow_upload_document_fileUpload a file to a documentA

Attach a local file to an existing document. Set main=true to mark it as the main document file. Use this together with wflow_update_document to create a document and attach its scan/PDF.

Inputs: filePath (required), documentId (required), main, organization.

wflow_upsert_registerCreate/update register entries (import a reference table)A

Write entries to a register. Two modes: • method='PUT' replaces the WHOLE set — entries missing from your list are marked invalid (this is how ERP reference-table imports work). Match is by externalId, or code if externalId is empty. • method='PATCH' updates only the entries you send, leaving the rest untouched. Each entry: {externalId?, code, description?, isValid?}.

Inputs: type (required), entries (required), method, organization.

wflow_upsert_roleCreate or update a roleA

Create a role (POST, omit id) or update it (PUT, pass roleId). Body: {name, description?, users?:[userId...], rights?:[Right...]}. Rights are enum names like CanApprove, CanMarkForPayment, CanExport, CanManageSettings.

Inputs: role (required), roleId, organization.

wflow_upsert_teamCreate or update a teamA

Create a team (POST, omit id) or update it (PUT, pass teamId). Body: {name, description?, users?:[userId...]}. This is how you 'create a new team X and add these users to it'.

Inputs: team (required), teamId, organization.

wflow_upsert_userAdd or update a userA

Add (by login) or update a user's access. Body fields: {login, hasFullAccess?, roles?:[{id}], teams?:[{id}], documentTypes?:[{id,permission}]}. permission ∈ All | OnlyAssigned | FullAccess. Unspecified fields are left unchanged.

Inputs: user (required), organization.

wflow_whoamiWho am IA

Return the authenticated account/identity for an organization (GET /account). Useful to confirm auth is working and see the acting user.

Inputs: organization.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 26 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: roles, teams, documents, registers, users, orgs, plus discovery/escape-hatch tools. Even create_document_with_files vs update_document are clearly separated by file attachment vs inline line items, and api_catalog/request serve unique discovery/execution roles.

    Naming Consistency4/5

    Tools consistently follow a verb_noun pattern (list_*, get_*, upsert_*, delete_*, create_*, search_*, update_*). Minor exceptions like wflow_whoami, wflow_api_catalog, and wflow_request break the strict verb-first scheme but remain predictable and readable.

    Tool Count4/5

    26 tools is above the typical 15-tool comfort zone, but the server covers a broad enterprise domain (documents, users, teams, roles, registers, organizations) plus low-level discovery/request capabilities. Most tools earn their place, though a unified document creation tool could reduce redundancy.

    Completeness3/5

    Documents, users, teams, roles, and registers have solid CRUD/lifecycle coverage, and bulk/export/event operations are a plus. However, there is no typed get_role, no document delete, and no approval/workflow action tools; these are deferred to the generic wflow_api_catalog/wflow_request escape hatch, which mitigates but does not fully cover the gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      🪄 MCP server for programmatic creation and management of n8n workflows. Enables AI assistants to build, modify, and manage workflows without direct user intervention through a comprehensive set of tools and resources for interacting with n8n's REST API.
      10
      29 npm
      86
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for OData v4 endpoints, especially Microsoft Dataverse/Dynamics 365, enabling authentication, schema discovery, querying, CRUD, and more via natural language.
      MIT