Skip to main content
Glama
Workadu MCP Server

Workadu MCP Server

Official
by workadu

Workadu MCP Server

MCP (Model Context Protocol) server for Workadu โ€” enables AI assistants to interact with your Workadu data through natural language.

What is this?

This server exposes Workadu's API as MCP tools, allowing AI assistants like Claude, Cursor, and others to:

  • ๐Ÿ“ฆ Manage Orders/Bookings โ€” list, create, update, cancel orders

  • ๐Ÿ‘ฅ Manage Customers โ€” search, create, update customer records

  • ๐Ÿ›Ž Manage Services โ€” CRUD operations on services/products

  • ๐Ÿงพ Manage Invoices โ€” create, publish, add lines, manage withholdings

  • ๐Ÿ’ฐ Manage Payments โ€” list and create payments

  • ๐Ÿ“ฆ Manage Assets โ€” CRUD operations on assets (DCL module)

  • ๐Ÿšš Manage Asset Movements โ€” create, close, cancel dispatch notes

Related MCP server: MCP Server for Odoo

Prerequisites

  • Node.js >= 18.0.0

  • A Workadu account with API access enabled

  • Your Workadu API key (from CompanyUser settings)

Installation

# Clone the repository
git clone https://github.com/workadu/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build
npm run build

Configuration

The server requires two environment variables:

Variable

Description

Example

WORKADU_API_URL

Your Workadu instance URL

https://your-app.workadu.com

WORKADU_API_KEY

Your API key

abc123...

Copy .env.example to .env and fill in your values:

cp .env.example .env

Usage

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "workadu": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "WORKADU_API_URL": "https://your-app.workadu.com",
        "WORKADU_API_KEY": "your-api-key-here"
      }
    }
  }
}

With Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "workadu": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "WORKADU_API_URL": "https://your-app.workadu.com",
        "WORKADU_API_KEY": "your-api-key-here"
      }
    }
  }
}

Testing with MCP Inspector

npm run inspect

This opens the MCP Inspector UI where you can test all tools interactively.

Direct execution

WORKADU_API_URL=https://your-app.workadu.com \
WORKADU_API_KEY=your-api-key \
npm start

Available Tools

Orders/Bookings

Tool

Description

list_orders

List orders/bookings with filters (date, status, customer)

get_order

Get order details by ID

create_order

Create a new booking/order

update_order

Update an existing order

delete_order

Cancel/delete an order

email_order

Send order confirmation email

Customers

Tool

Description

list_customers

List customers (paginated, searchable)

get_customer

Get customer details by ID

create_customer

Create a new customer

update_customer

Update an existing customer

Services

Tool

Description

list_services

List services/products

get_service

Get service details by ID

create_service

Create a new service

update_service

Update an existing service

delete_service

Delete a service

Invoices

Tool

Description

list_invoices

List invoices with filters

get_invoice

Get invoice details by ID

create_invoice

Create a new invoice

create_invoice_with_lines

Create invoice with line items

add_invoice_line

Add a line to existing invoice

update_invoice

Update an existing invoice

publish_invoice

Publish/finalize a draft invoice

list_series

List invoice series

list_withholdings

List withholdings for an invoice

create_withholding

Add withholding to an invoice

Payments

Tool

Description

list_payments

List payments

create_payment

Create a new payment

Invoice creation and update accept optional payment_type: the Workadu payment series ID returned by list_series, rather than an AADE payment method code. create_invoice_with_lines also accepts these optional inputs:

  • related_invoice_id: a string of comma-separated original invoice IDs, e.g. "123" or "123,456".

  • tags: an array of tag names or an array of existing tag IDs.

  • referrer_unique_id: an external reference for the REST API's duplicate detection.

Each create_invoice_with_lines line also accepts optional oss_vat as a numeric rate from 0 to 100. It is valid only for an OSS-enabled invoice series; the API derives oss_country from the customer's country and rejects country overrides. OSS invoice responses expose oss_vat and oss_country on the affected lines. add_invoice_line accepts the same oss_vat input.

The tool sends customer_id as customer.id and nests invoice fields under invoice, including currency_iso as REST currency. Line unit_price is sent as amount, and optional discount_percent as line_discount. This endpoint does not support service_id or admin_notes.

update_invoice accepts optional tags as comma-separated tag names. This replaces the invoice's tags, so include existing tags that should be kept. The REST endpoint does not support clearing all tags with an empty string. Updating contact tags still requires a REST API change.

update_invoice also accepts transporter_id, shipping_address, dispatch_date (YYYY-MM-DD), and dispatch_time (HH:mm:ss). Automatic payment and editing/deleting invoice lines still require REST API support.

publish_invoice accepts optional aade_send and send. Set aade_send: true to explicitly request myDATA submission, including for an already VALID invoice. Omitted options remain omitted from the REST request. Check the returned meta.myData or pending POS response; HTTP success alone does not confirm AADE acceptance.

Invoice and payment listing map from_date/to_date to REST issue_date_from/issue_date_to. Invoice date filtering requires both bounds. Payments can also be filtered by customer_id. Both tools accept sort (prefix the field with - for descending), but invoice sorting affects only the current page. The invoice REST endpoint still fixes page size at 100. Customer search is sent using the REST filter[search_term] parameter. Customer balance and configurable invoice pagination/global sorting still require REST API changes.

create_payment accepts optional invoice_ids as a comma-separated string. For all payments, it sends amount as REST deposit, series_id as REST series, and optional comments as REST comment. Choose the appropriate payment or refund series; invoice_ids links the payment to those invoices. It also accepts optional issue_date in YYYY-MM-DD format and sends it as the payment date. Omit it to use today's date; historical dates are supported. The REST endpoint uses the company's configured currency regardless of the supplied currency_iso value.

Assets (DCL)

Tool

Description

list_assets

List assets

get_asset

Get asset details by ID

create_asset

Create a new asset

update_asset

Update an existing asset

delete_asset

Delete an asset

Asset Movements (DCL)

Tool

Description

list_asset_movements

List asset movements

get_asset_movement

Get movement details by ID

create_asset_movement

Create a new movement

close_asset_movement

Close/finalize a movement

cancel_asset_movement

Cancel a movement

resend_asset_movement

Resend movement notification

Development

# Watch mode (auto-recompile on changes)
npm run dev

# Type checking
npm run lint

# Build
npm run build

Architecture

src/
โ”œโ”€โ”€ index.ts              # Entry point โ€” MCP Server init
โ”œโ”€โ”€ config.ts             # Environment config
โ”œโ”€โ”€ client/
โ”‚   โ””โ”€โ”€ workadu-client.ts # HTTP client for Workadu Dingo API
โ”œโ”€โ”€ tools/
โ”‚   โ”œโ”€โ”€ index.ts          # Tool registry
โ”‚   โ”œโ”€โ”€ orders.ts         # Order/booking tools
โ”‚   โ”œโ”€โ”€ customers.ts      # Customer tools
โ”‚   โ”œโ”€โ”€ services.ts       # Service tools
โ”‚   โ”œโ”€โ”€ invoices.ts       # Invoice tools
โ”‚   โ”œโ”€โ”€ payments.ts       # Payment tools
โ”‚   โ”œโ”€โ”€ assets.ts         # Asset tools
โ”‚   โ””โ”€โ”€ asset-movements.ts # Asset movement tools
โ””โ”€โ”€ types/
    โ””โ”€โ”€ workadu.ts        # TypeScript type definitions

Authentication

The server authenticates with Workadu using the existing API key mechanism:

  • Sends Authorization: Basic base64(api_key:) header

  • Sends Dingo version header: Accept: application/vnd.rengine.v2+json

  • All API calls are automatically scoped to the company associated with the API key

License

UNLICENSED โ€” Proprietary Workadu software

Available Tools

38 tools
add_invoice_lineB

Add a line item to an existing draft invoice.

Inputs: invoice_id (required), description (required), quantity (required), unit_price (required), +3 more.

cancel_asset_movementC

Cancel an asset movement in Workadu.

Inputs: id (required).

close_asset_movementB

Close/finalize an asset movement in Workadu.

Inputs: id (required).

create_assetB

Create a new asset (DCL module). Requires name and code.

Inputs: name (required), code (required), description, category_id.

create_asset_movementB

Create a new asset movement (dispatch note, transfer) in Workadu.

Inputs: asset_id (required), type (required), quantity, source, +2 more.

create_customerB

Create a new customer. Only fullname is required; all other fields are optional.

Inputs: fullname (required), email, mobile, country, +11 more.

create_invoiceA

Create a new draft invoice (without lines). Use add_invoice_line to add lines, then publish_invoice to finalize.

Inputs: issue_date (required), customer_id (required), series_id (required), includes_vat, +3 more.

create_invoice_with_linesB

Create a new draft invoice with line items in a single call. Each line specifies a product/service, quantity, and pricing.

Inputs: issue_date (required), customer_id (required), series_id (required), lines (required), +4 more.

create_orderC

Create a new order/booking. Requires customer, service, and date range. Optionally specify pickup/return times, a comment, and a calendar color.

Inputs: customer_id (required), service_id (required), pickup_date (required), return_date (required), +4 more.

create_paymentC

Create a new payment. Requires issue date, customer, series, amount, and currency.

Inputs: issue_date (required), customer_id (required), series_id (required), amount (required), +5 more.

create_serviceB

Create a new service/product in Workadu. Title is required; other fields are optional.

Inputs: title (required), description, brand, category_id, +5 more.

create_withholdingB

Add a withholding tax deduction to an invoice.

Inputs: invoice_id (required), type (required), category (required), amount, +1 more.

delete_assetB

Delete an asset by ID (DCL module).

Inputs: id (required).

delete_orderB

Delete (cancel) an order/booking by its ID.

Inputs: id (required).

delete_serviceB

Delete a service/product from Workadu.

Inputs: id (required).

email_orderB

Email an order/booking confirmation or details to a specified email address.

Inputs: order_id (required), email (required).

get_assetA

Retrieve a specific asset by ID (DCL module).

Inputs: id (required).

get_asset_movementB

Get details of a specific asset movement by ID from Workadu.

Inputs: id (required).

get_customerA

Get a specific customer by ID. Returns full customer details including decrypted PII fields.

Inputs: id (required).

get_invoiceA

Get details of a specific invoice by ID, including lines, customer, and series info.

Inputs: id (required).

get_orderA

Get a specific order/booking by its ID, including sub-orders, customer info, and related data.

Inputs: id (required).

get_serviceA

Get details of a specific service/product by ID, including rates, media, and attributes.

Inputs: id (required).

list_asset_movementsB

List asset movements (dispatch notes, transfers) from Workadu. Supports pagination.

Inputs: page, per_page.

list_assetsA

List all assets (DCL module).

Inputs: no named parameters.

list_customersA

List customers (paginated, 50 per page by default). Supports search by name/email/mobile.

Inputs: page, per_page, search.

list_invoicesB

List invoices/documents with optional filters. Statuses: CANCELED=0, PUBLISHED=1, DRAFT=2, PREVIEW=99.

Inputs: page, per_page, status, customer_id, +3 more.

list_ordersA

List orders/bookings with optional filters for status, customer, date range, and pagination. In Workadu, "orders" at the API level represent Bookings (top-level entities containing sub-orders/items).

Inputs: page, per_page, status, customer_id, +2 more.

list_paymentsA

List payments or retrieve a specific payment by ID. Payment statuses: ACTIVE=1, DRAFT=2, FAILED=3, REFUNDED=4.

Inputs: id, page, per_page.

list_seriesB

List invoice series (document types). Series define the numbering and type of document (e.g. Invoice, Receipt, Credit Note).

Inputs: id.

list_servicesB

List all services/products from Workadu. Supports pagination.

Inputs: page, per_page.

list_withholdingsA

List withholding tax deductions for a specific invoice.

Inputs: invoice_id (required).

publish_invoiceA

Publish/finalize a draft invoice. WARNING: This is IRREVERSIBLE โ€” once published, the invoice is submitted to AADE (Greek tax authority) and cannot be edited.

Inputs: invoice_id (required).

resend_asset_movementC

Resend an asset movement notification in Workadu.

Inputs: id (required).

update_assetA

Update an existing asset by ID (DCL module). Only provided fields will be changed.

Inputs: id (required), name, code, description, +1 more.

update_customerA

Update an existing customer by ID. Only the provided fields will be changed.

Inputs: id (required), fullname, email, mobile, +12 more.

update_invoiceA

Update an existing draft invoice. Only the provided fields will be changed. Cannot update published invoices.

Inputs: id (required), issue_date, customer_id, series_id, +5 more.

update_orderA

Update an existing order/booking. Only the fields you provide will be changed.

Inputs: id (required), customer_id, service_id, pickup_date, +5 more.

update_serviceB

Update an existing service/product. Only the provided fields will be changed.

Inputs: id (required), title, description, brand, +6 more.

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 38 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action, with no overlapping functionality. Even similar tools like create_invoice and create_invoice_with_lines are for different use cases (step-by-step vs. one-shot).

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in lowercase with underscores (e.g., create_asset, list_invoices, update_customer). No mixing of styles.

    Tool Count4/5

    38 tools is slightly above average, but the breadth of functionality (assets, customers, invoices, orders, payments, services) justifies the count. Each tool serves a clear purpose without redundancy.

    Completeness4/5

    CRUD operations are covered for most resources (assets, customers, services, orders, invoices). Minor gaps: no delete_customer or update/delete_payment, but invoice and order workflows are thorough.

    Related MCP Connectors

    Related MCP Servers