MCP 服务器

Wave MCP Server

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

README

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

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" 
});