Wave Accounting MCP Server

A production-ready Model Context Protocol (MCP) server for Wave Accounting, built with Node.js and TypeScript. This server provides tools to interact with Wave Accounting's GraphQL API, enabling you to create expenses, income transactions, invoices, and manage customers, vendors, and accounts.

Quick Start (Recommended)

For Claude Desktop

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wave": {
      "command": "npx",
      "args": ["-y", "wave-mcp-server@latest"],
      "env": {
        "WAVE_ACCESS_TOKEN": "your_wave_access_token_here"
      }
    }
  }
}

For OpenCode

Add the following to your OpenCode MCP configuration:

{
  "mcpServers": {
    "wave": {
      "command": "npx",
      "args": ["-y", "wave-mcp-server@latest"],
      "env": {
        "WAVE_ACCESS_TOKEN": "your_wave_access_token_here"
      }
    }
  }
}

For Cursor

Add the following to your Cursor settings (Settings > MCP):

{
  "mcpServers": {
    "wave": {
      "command": "npx",
      "args": ["-y", "wave-mcp-server@latest"],
      "env": {
        "WAVE_ACCESS_TOKEN": "your_wave_access_token_here"
      }
    }
  }
}

Or add via Cursor's MCP settings UI by creating a new MCP server with:

• Name: wave
• Command: npx
• Args: -y wave-mcp-server@latest
• Env: WAVE_ACCESS_TOKEN=your_token_here

Features

• 17 MCP Tools:

  Business (2):

  • list_businesses - List all available Wave businesses with pagination
  • set_business - Set the active business for operations

  Expenses (3):

  • create_expense_from_receipt - Create expenses from receipt data
  • search_vendor - Search for existing vendors
  • get_expense_accounts - List expense accounts

  Income (3):

  • create_income_from_payment - Create income transactions
  • search_customer - Search for existing customers
  • get_income_accounts - List income accounts

  Invoices (8):

  • list_invoices - List invoices with pagination
  • get_invoice - Get detailed invoice information
  • create_invoice - Create new invoice
  • update_invoice - Modify existing invoice
  • delete_invoice - Delete an invoice
  • clone_invoice - Copy an invoice
  • approve_invoice - Approve draft invoice
  • send_invoice - Email invoice to customers

  Debug (1):

  • debug_accounts - Debug tool for account issues

• 4 MCP Resources:

  • wave://businesses - Business information
  • wave://accounts - Chart of accounts
  • wave://vendors - Vendors list
  • wave://customers - Customers list

• Smart Account Matching:

  • Fuzzy matching with synonyms
  • Apartment/property number detection for rental accounts
  • Multi-stage matching with confidence scoring

• Multi-Business Support:

  • Pagination support for large datasets
  • Auto-selection of single business
  • Optional manual business selection

Getting a Wave Access Token

1. Log into Wave at https://waveapps.com
2. Go to Settings > Developer > API Access
3. Create a new OAuth2 application
4. Generate an access token

Manual Installation

If you prefer to install and run locally:

# Clone the repository
git clone https://github.com/yourusername/wave-mcp-server.git
cd wave-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

Configuration

Create a .env file in the project root:

# REQUIRED: Your Wave API access token (OAuth2 Bearer token)
WAVE_ACCESS_TOKEN=your_wave_access_token_here

# OPTIONAL: Your Wave business ID (auto-detected if not provided)
WAVE_BUSINESS_ID=

# OPTIONAL: Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

See .env.example for more details.

Local Development Config

For local development with Claude Desktop, use this config instead:

{
  "mcpServers": {
    "wave": {
      "command": "node",
      "args": ["/absolute/path/to/wave-mcp-server/dist/server.js"],
      "env": {
        "WAVE_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools

Business Management

• list_businesses - List all businesses with pagination support
• set_business - Set the active business context

Expense Management

• create_expense_from_receipt - Create expenses from receipt data
• search_vendor - Find vendors by name or email
• get_expense_accounts - List available expense accounts

Income Management

• create_income_from_payment - Create income transactions from payment data
• search_customer - Find customers by name or email
• get_income_accounts - List available income accounts

Invoice Management

• list_invoices - List all invoices with filtering and pagination
• get_invoice - Get detailed information for a specific invoice
• create_invoice - Create a new invoice with items, discounts, etc.
• update_invoice - Modify an existing invoice
• delete_invoice - Delete an invoice
• clone_invoice - Copy an existing invoice
• approve_invoice - Approve a draft invoice (change status from DRAFT to SAVED)
• send_invoice - Send an invoice via email to customers

Debug Tools

• debug_accounts - Inspect accounts and test account matching

Resources

• wave://businesses - View all your businesses
• wave://accounts - Browse your chart of accounts
• wave://vendors - List all vendors
• wave://customers - List all customers

Project Structure

wave-mcp-server/
├── src/
│   ├── server.ts                  # Main entry point
│   ├── client/
│   │   ├── WaveClient.ts          # GraphQL API client
│   │   ├── types.ts               # TypeScript interfaces and Zod schemas
│   │   └── queries.ts             # GraphQL query constants
│   ├── handlers/
│   │   ├── tools/
│   │   │   ├── index.ts           # Tool registry
│   │   │   ├── expenseTools.ts    # Expense-related tools
│   │   │   ├── incomeTools.ts     # Income-related tools
│   │   │   ├── invoiceTools.ts    # Invoice-related tools
│   │   │   ├── businessTools.ts   # Business management tools
│   │   │   └── debugTools.ts      # Debug tools
│   │   └── resources/
│   │       └── index.ts           # Resource handlers
│   ├── utils/
│   │   ├── accountMatcher.ts      # Smart account matching
│   │   ├── synonyms.ts            # Category synonyms
│   │   └── logger.ts              # Logging utility
│   └── config/
│       └── env.ts                 # Environment configuration
├── dist/                           # Compiled JavaScript (generated by tsc)
├── .env.example                    # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

Key Features

• Smart account matching with fuzzy matching
• Apartment/property number detection for rental accounts
• Multi-business support with pagination
• Optional vendor/customer association
• Payment/deposit account selection
• Comprehensive debug tool
• Full invoice CRUD operations

License

ISC