# Wave MCP Server

An MCP server for [Wave Accounting](https://waveapps.com), providing access to invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting via Wave's GraphQL API.

## Features

### 54 Tools across 10 categories

| Category | Tools | Capabilities |
|---|---|---|
| **Invoices** | 10 | List, get, create, update, delete, send, approve, mark sent, list/record payments |
| **Customers** | 6 | List, get, create, update, delete, search by name/email |
| **Products** | 5 | List, get, create, update, archive products and services |
| **Accounts** | 4 | List, get, create, update chart of accounts |
| **Transactions** | 6 | List, get, create, update, categorize, list attachments |
| **Bills** | 6 | List, get, create, update, list/record bill payments |
| **Estimates** | 6 | List, get, create, update, send, convert to invoice |
| **Taxes** | 3 | List, get, create sales taxes |
| **Businesses** | 3 | List, get current, get by ID |
| **Reporting** | 5 | P&L, Balance Sheet, Aged Receivables, Tax Summary, Cashflow |

### 17 MCP App Resources

Pre-built UI layout definitions accessible via `wave://apps/{name}`:

`invoice-dashboard`, `invoice-detail`, `invoice-builder`, `customer-detail`, `customer-grid`, `product-catalog`, `chart-of-accounts`, `transaction-feed`, `transaction-categorizer`, `bill-manager`, `estimate-builder`, `tax-overview`, `profit-loss`, `balance-sheet`, `cashflow-chart`, `aging-report`, `business-overview`

## Prerequisites

1. A [Wave](https://waveapps.com) account
2. An OAuth2 access token from the [Wave Developer Portal](https://developer.waveapps.com/)

## Installation

```bash
npm install
npm run build
```

## Configuration

```bash
# Required
export WAVE_ACCESS_TOKEN=your_oauth2_access_token

# Optional — set a default business ID so you don't have to pass it every call
export WAVE_BUSINESS_ID=your_business_id
```

## Usage

### Run directly

```bash
WAVE_ACCESS_TOKEN=your_token npm run dev
```

### With Cursor / Claude Desktop

Add to your MCP config:

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

## Examples

```typescript
// List overdue invoices
wave_list_invoices({ status: "OVERDUE" })

// Create an invoice
wave_create_invoice({
  customerId: "customer_456",
  invoiceDate: "2026-01-15",
  items: [
    { description: "Consulting", quantity: 10, unitPrice: "150.00" }
  ]
})

// Profit & Loss report
wave_profit_and_loss({ startDate: "2026-01-01", endDate: "2026-03-31" })

// Search customers
wave_search_customers({ query: "acme" })
```

## Architecture

```
src/
├── main.ts                 # Entry point — reads env, starts server
├── server.ts               # MCP server setup, request routing
├── client.ts               # Wave GraphQL API client (gql.waveapps.com)
├── types/index.ts           # TypeScript types for all Wave entities
├── tools/
│   ├── invoices-tools.ts    # 10 invoice tools
│   ├── customers-tools.ts   # 6 customer tools
│   ├── products-tools.ts    # 5 product tools
│   ├── accounts-tools.ts    # 4 account tools
│   ├── transactions-tools.ts # 6 transaction tools
│   ├── bills-tools.ts       # 6 bill tools
│   ├── estimates-tools.ts   # 6 estimate tools
│   ├── taxes-tools.ts       # 3 tax tools
│   ├── businesses-tools.ts  # 3 business tools
│   └── reporting-tools.ts   # 5 reporting tools
└── apps/index.ts            # 17 MCP app resource definitions
```

All tools use parameterized GraphQL queries against `https://gql.waveapps.com/graphql/public`. Auth is via OAuth2 Bearer token.

## Development

```bash
npm run build     # Compile TypeScript
npm run watch     # Watch mode
npx tsc --noEmit  # Type-check without emitting
```

## License

MIT