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:

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

Customers

Services

Invoices

Payments

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.

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. The current REST endpoint assigns the creation date and the company's currency, regardless of the supplied issue_date and currency_iso; backdated payments require REST API support.

Assets (DCL)

Asset Movements (DCL)

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