How do I use Wave MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Wave MCP Server list all unpaid invoices from last month" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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:

invoice-dashboard - Overview of invoices with status breakdown
invoice-detail - Detailed invoice view with payments and actions
invoice-builder - Create/edit invoices with line items
customer-detail - Customer profile with invoice history
customer-grid - Searchable customer grid
product-catalog - Product/service management
chart-of-accounts - Account tree view
transaction-feed - Real-time transaction stream
transaction-categorizer - Bulk transaction categorization
bill-manager - Track and pay bills
estimate-builder - Create and manage quotes
tax-overview - Tax configuration and summary
profit-loss - P&L report with visualization
balance-sheet - Balance sheet report
cashflow-chart - Cashflow waterfall chart
aging-report - Aged receivables report
business-overview - Business dashboard with quick actions

Related MCP server: mercury-invoicing-mcp

Installation

cd servers/wave
npm install
npm run build

Configuration

Prerequisites

Wave Account: You need a Wave account at waveapps.com
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:

Wave API issues: Wave Developer Support
MCP Server issues: GitHub Issues