Skip to main content
Glama
Wave MCP Server

Wave MCP Server

by mvicari

Wave MCP Server

A complete Model Context Protocol (MCP) server for Wave Accounting, providing comprehensive access to invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting.

Features

πŸ”§ 45+ Tools across 10 categories:

Invoices (10 tools)

  • List, get, create, update, delete invoices

  • Send invoices via email

  • Approve and mark invoices as sent

  • List and record invoice payments

Customers (6 tools)

  • List, get, create, update, delete customers

  • Search customers by name or email

Products (5 tools)

  • List, get, create, update, archive products and services

  • Filter by sold/bought status

Accounts (4 tools)

  • List, get, create, update chart of accounts

  • Filter by account type (ASSET, LIABILITY, EQUITY, INCOME, EXPENSE)

Transactions (6 tools)

  • List, get, create, update transactions

  • Categorize transactions to accounts

  • List transaction attachments

Bills (7 tools)

  • List, get, create, update bills (accounts payable)

  • List and record bill payments

Estimates (6 tools)

  • List, get, create, update, send estimates

  • Convert estimates to invoices

Taxes (3 tools)

  • List, get, create sales taxes

Businesses (3 tools)

  • List businesses

  • Get current or specific business details

Reporting (5 tools)

  • Profit & Loss (Income Statement)

  • Balance Sheet

  • Aged Receivables (A/R Aging)

  • Tax Summary

  • Cashflow Statement

πŸ“± 17 MCP Apps - Pre-built UI workflows:

  1. invoice-dashboard - Overview of invoices with status breakdown

  2. invoice-detail - Detailed invoice view with payments and actions

  3. invoice-builder - Create/edit invoices with line items

  4. customer-detail - Customer profile with invoice history

  5. customer-grid - Searchable customer grid

  6. product-catalog - Product/service management

  7. chart-of-accounts - Account tree view

  8. transaction-feed - Real-time transaction stream

  9. transaction-categorizer - Bulk transaction categorization

  10. bill-manager - Track and pay bills

  11. estimate-builder - Create and manage quotes

  12. tax-overview - Tax configuration and summary

  13. profit-loss - P&L report with visualization

  14. balance-sheet - Balance sheet report

  15. cashflow-chart - Cashflow waterfall chart

  16. aging-report - Aged receivables report

  17. business-overview - Business dashboard with quick actions

Related MCP server: waveapps-mcp

Installation

cd servers/wave
npm install
npm run build

Configuration

Prerequisites

  1. Wave Account: You need a Wave account at waveapps.com

  2. API Access Token: Get an OAuth2 access token from Wave Developer Portal

Environment Variables

# Required
WAVE_ACCESS_TOKEN=your_oauth2_access_token

# Optional - set a default business ID
WAVE_BUSINESS_ID=your_business_id

Usage

As MCP Server

Run the server:

WAVE_ACCESS_TOKEN=your_token npm run dev

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "wave": {
      "command": "node",
      "args": ["/path/to/mcpengine-repo/servers/wave/build/main.js"],
      "env": {
        "WAVE_ACCESS_TOKEN": "your_access_token",
        "WAVE_BUSINESS_ID": "optional_business_id"
      }
    }
  }
}

With NPX

npx @mcpengine/wave-server

Tool Examples

List Invoices

// List all invoices
wave_list_invoices({ businessId: "business_123" })

// Filter by status
wave_list_invoices({ 
  businessId: "business_123",
  status: "OVERDUE"
})

// Filter by customer
wave_list_invoices({
  businessId: "business_123", 
  customerId: "customer_456"
})

Create Invoice

wave_create_invoice({
  businessId: "business_123",
  customerId: "customer_456",
  invoiceDate: "2025-01-15",
  dueDate: "2025-02-15",
  title: "January Services",
  items: [
    {
      description: "Consulting Services",
      quantity: 10,
      unitPrice: "150.00",
      taxIds: ["tax_789"]
    },
    {
      productId: "product_101",
      description: "Software License",
      quantity: 1,
      unitPrice: "500.00"
    }
  ]
})

Create Customer

wave_create_customer({
  businessId: "business_123",
  name: "Acme Corporation",
  email: "billing@acme.com",
  addressLine1: "123 Main Street",
  city: "San Francisco",
  provinceCode: "CA",
  countryCode: "US",
  postalCode: "94105"
})

Generate Reports

// Profit & Loss
wave_profit_and_loss({
  businessId: "business_123",
  startDate: "2025-01-01",
  endDate: "2025-01-31"
})

// Balance Sheet
wave_balance_sheet({
  businessId: "business_123",
  asOfDate: "2025-01-31"
})

// Aged Receivables
wave_aged_receivables({
  businessId: "business_123",
  asOfDate: "2025-01-31"
})

API Architecture

GraphQL-Based

Wave uses a GraphQL API, not REST. The server handles:

  • Authentication: OAuth2 Bearer token

  • Error Handling: GraphQL error parsing and network error detection

  • Type Safety: Full TypeScript types for all Wave entities

  • Pagination: Automatic page handling for large result sets

Client Implementation

// client.ts
import { GraphQLClient } from 'graphql-request';

const client = new GraphQLClient('https://gql.waveapps.com/graphql/public', {
  headers: {
    Authorization: `Bearer ${accessToken}`
  }
});

Tool Organization

src/tools/
β”œβ”€β”€ invoices-tools.ts      # 10 tools for invoice management
β”œβ”€β”€ customers-tools.ts     # 6 tools for customer management
β”œβ”€β”€ products-tools.ts      # 5 tools for product/service catalog
β”œβ”€β”€ accounts-tools.ts      # 4 tools for chart of accounts
β”œβ”€β”€ transactions-tools.ts  # 6 tools for transaction management
β”œβ”€β”€ bills-tools.ts         # 7 tools for bills payable
β”œβ”€β”€ estimates-tools.ts     # 6 tools for estimates/quotes
β”œβ”€β”€ taxes-tools.ts         # 3 tools for sales tax management
β”œβ”€β”€ businesses-tools.ts    # 3 tools for business info
└── reporting-tools.ts     # 5 tools for financial reports

Type System

Complete TypeScript types for all Wave entities:

// types/index.ts
export interface Invoice {
  id: string;
  invoiceNumber: string;
  customer: Customer;
  status: 'DRAFT' | 'SENT' | 'VIEWED' | 'PAID' | 'PARTIAL' | 'OVERDUE' | 'APPROVED';
  items: InvoiceItem[];
  total: Money;
  amountDue: Money;
  amountPaid: Money;
  // ... full type definitions
}

Error Handling

The server provides comprehensive error handling:

try {
  const invoice = await wave_get_invoice({ invoiceId: "inv_123" });
} catch (error) {
  // GraphQL errors
  if (error.graphQLErrors) {
    console.error('GraphQL errors:', error.graphQLErrors);
  }
  
  // Network errors
  if (error.networkError) {
    console.error('Network error:', error.networkError);
  }
  
  // HTTP status codes
  if (error.statusCode) {
    console.error('HTTP status:', error.statusCode);
  }
}

MCP Apps

Apps are accessed via resources:

// List all apps
const apps = await readResource({ uri: "wave://apps" });

// Load specific app
const invoiceDashboard = await readResource({ 
  uri: "wave://apps/invoice-dashboard" 
});

Each app includes:

  • Display name and description

  • Default tools to load

  • Layout configuration for UI rendering

  • Workflow steps (for process-driven apps)

Development

Build

npm run build

Watch Mode

npm run watch

Type Checking

npx tsc --noEmit

License

MIT

Contributing

Contributions welcome! Please see the main MCPEngine repository for guidelines.

Support

For issues or questions:

Available Tools

54 tools
wave_aged_receivablesB

Generate an Aged Receivables (A/R Aging) report

Inputs: asOfDate, businessId.

wave_approve_invoiceC

Approve a draft invoice

Inputs: invoiceId (required), businessId.

wave_balance_sheetB

Generate a Balance Sheet report

Inputs: asOfDate (required), businessId.

wave_cashflowC

Generate a cashflow statement for a date range

Inputs: endDate (required), startDate (required), businessId.

wave_categorize_transactionC

Categorize/recategorize a transaction to a different account

Inputs: accountId (required), transactionId (required), businessId.

wave_convert_estimate_to_invoiceB

Convert an approved estimate into an invoice

Inputs: estimateId (required), dueDate, businessId, invoiceDate.

wave_create_accountA

Create a new account in the chart of accounts

Inputs: name (required), type (required), subtype, currency, +2 more.

wave_create_billC

Create a new bill

Inputs: items (required), billDate (required), vendorId (required), memo, +3 more.

wave_create_bill_paymentB

Record a payment made for a bill

Inputs: date (required), amount (required), billId (required), source, +1 more.

wave_create_customerC

Create a new customer

Inputs: name (required), city, email, currency, +8 more.

wave_create_estimateB

Create a new estimate (quote)

Inputs: items (required), customerId (required), estimateDate (required), memo, +5 more.

wave_create_invoiceC

Create a new invoice

Inputs: items (required), customerId (required), invoiceDate (required), memo, +5 more.

wave_create_invoice_paymentC

Record a payment received for an invoice

Inputs: date (required), amount (required), invoiceId (required), source, +1 more.

wave_create_productC

Create a new product or service

Inputs: name (required), isSold, isBought, unitPrice, +3 more.

wave_create_taxB

Create a new sales tax

Inputs: name (required), rate (required), businessId, description, +1 more.

wave_create_transactionC

Create a new transaction

Inputs: date (required), amount (required), accountId (required), description (required), +1 more.

wave_delete_customerA

Delete a customer (only if they have no invoices)

Inputs: customerId (required), businessId.

wave_delete_invoiceA

Delete an invoice (must be in DRAFT status)

Inputs: invoiceId (required), businessId.

wave_delete_productB

Delete (archive) a product or service

Inputs: productId (required), businessId.

wave_get_accountA

Get detailed information about a specific account

Inputs: accountId (required), businessId.

wave_get_billC

Get detailed information about a specific bill

Inputs: billId (required), businessId.

wave_get_businessA

Get detailed information about a specific business

Inputs: businessId (required).

wave_get_current_businessA

Get the currently active business (if businessId is set globally)

Inputs: no named parameters.

wave_get_customerA

Get detailed information about a specific customer

Inputs: customerId (required), businessId.

wave_get_estimateB

Get detailed information about a specific estimate

Inputs: estimateId (required), businessId.

wave_get_invoiceC

Get detailed information about a specific invoice

Inputs: invoiceId (required), businessId.

wave_get_productB

Get detailed information about a specific product or service

Inputs: productId (required), businessId.

wave_get_taxC

Get detailed information about a specific tax

Inputs: taxId (required), businessId.

wave_get_transactionB

Get detailed information about a specific transaction

Inputs: transactionId (required), businessId.

wave_list_accountsB

List all accounts in the chart of accounts

Inputs: page, type, pageSize, businessId, +1 more.

wave_list_bill_paymentsB

List payments made for a specific bill

Inputs: billId (required), businessId.

wave_list_billsB

List bills (accounts payable) for a business

Inputs: page, status, pageSize, vendorId, +1 more.

wave_list_businessesA

List all businesses accessible with the current access token

Inputs: no named parameters.

wave_list_customersC

List all customers for a business

Inputs: page, pageSize, businessId.

wave_list_estimatesC

List estimates (quotes) for a business

Inputs: page, status, pageSize, businessId, +1 more.

wave_list_invoice_paymentsA

List payments received for a specific invoice

Inputs: invoiceId (required), businessId.

wave_list_invoicesC

List invoices for a business with optional filtering

Inputs: page, status, pageSize, businessId, +1 more.

wave_list_productsC

List all products and services for a business

Inputs: page, isSold, isBought, pageSize, +2 more.

wave_list_taxesB

List all sales taxes configured for a business

Inputs: businessId, isArchived.

wave_list_transaction_attachmentsA

List attachments (receipts, documents) for a transaction

Inputs: transactionId (required), businessId.

wave_list_transactionsB

List transactions for a business with filtering options

Inputs: page, endDate, pageSize, accountId, +2 more.

wave_mark_invoice_sentA

Mark an invoice as sent (without actually sending email)

Inputs: invoiceId (required), businessId.

wave_profit_and_lossC

Generate a Profit & Loss (Income Statement) report

Inputs: endDate (required), startDate (required), businessId.

wave_search_customersA

Search customers by name or email

Inputs: query (required), limit, businessId.

wave_send_estimateB

Send an estimate to the customer via email

Inputs: estimateId (required), to, message, subject, +1 more.

wave_send_invoiceB

Send an invoice to the customer via email

Inputs: invoiceId (required), to, message, subject, +1 more.

wave_tax_summaryC

Generate a tax summary report for a date range

Inputs: endDate (required), startDate (required), businessId.

wave_update_accountC

Update an existing account

Inputs: accountId (required), name, businessId, description.

wave_update_billB

Update an existing bill

Inputs: billId (required), memo, dueDate, billNumber, +1 more.

wave_update_customerC

Update an existing customer

Inputs: customerId (required), city, name, email, +8 more.

wave_update_estimateC

Update an existing estimate

Inputs: estimateId (required), memo, title, footer, +3 more.

wave_update_invoiceC

Update an existing invoice

Inputs: invoiceId (required), memo, title, footer, +3 more.

wave_update_productB

Update an existing product or service

Inputs: productId (required), name, unitPrice, businessId, +2 more.

wave_update_transactionC

Update an existing transaction

Inputs: transactionId (required), date, businessId, description.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 54 tools

    Disambiguation5/5

    Each tool has a unique and descriptive name that clearly indicates its target entity and action (e.g., wave_create_invoice, wave_list_customers, wave_delete_product). There is no ambiguity between tools; an agent can easily distinguish them.

    Naming Consistency5/5

    All 54 tools follow a consistent verb_noun pattern with the 'wave_' prefix (e.g., wave_create_invoice, wave_get_customer, wave_list_accounts). The naming convention is uniform, making the tool surface predictable and easy to navigate.

    Tool Count4/5

    54 tools is on the higher end, but it is justified for a comprehensive accounting API covering multiple entities (customers, invoices, bills, products, taxes, transactions) and reports. Each tool serves a distinct purpose, and the count is appropriate for the domain.

    Completeness3/5

    Core CRUD and reporting operations are covered for most entities, but there are notable gaps: missing delete for bills, estimates, taxes, and transactions; no update for bill payments; and no delete for taxes. These omissions may hinder some workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      This project builds a read-only MCP server. For full read, write, update, delete, and action capabilities and a simplified setup, check out our free CData MCP Server for Wave Financial (beta): https://www.cdata.com/download/download.aspx?sku=HWZK-V&type=beta
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      This MCP server enables AI assistants like Claude to perform Wave Accounting bookkeeping tasksβ€”such as drafting invoices, managing customers, recording payments, and looking up financial dataβ€”through natural language commands.
      8
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Comprehensive MCP server for Wave Accounting, providing 45+ tools across invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting, plus 17 pre-built UI workflows.
      5
      MIT
    • F
      license
      A
      quality
      F
      maintenance
      MCP server for Wave accounting that provides tools for managing chart of accounts, invoices, customers, vendors, products, and reports via the Wave GraphQL API.
      6
      -