🚀 Don't want to self-host? Join the waitlist for our fully managed solution →

Zero setup. Zero maintenance. Just connect and automate.

---

📊 Wave MCP Server — AI-Native Small Business Accounting

💡 What This Unlocks

Free accounting software meets AI superpowers. This MCP server connects Claude to Wave's GraphQL API, giving you natural language control over invoices, customers, expenses, and financial data—no manual data entry required.

🎯 Wave-Native Power Moves

Real small business workflows you can automate instantly:

1. Bulk invoice generation for service businesses
   "For business ID abc123, create invoices for all customers who had transactions last month—use standard 30-day terms, group by customer, calculate totals automatically."
   → Generate 50 invoices in one prompt vs. hours of manual entry.

2. Customer database cleanup
   "List all customers with incomplete addresses, cross-reference with recent invoices, update missing postal codes and phone numbers from invoice metadata."
   → Clean CRM hygiene without tedious manual updates.

3. Expense categorization workflow
   "Pull all uncategorized transactions from my checking account, match merchants to expense categories using my historical patterns, create expense records with proper accounting codes."
   → Automated bookkeeping that used to require a dedicated bookkeeper.

4. Multi-business revenue dashboard
   "Query all my Wave businesses, show total invoiced vs. paid for each in the last quarter, flag businesses with overdue invoices > $500."
   → Cross-business intelligence from Wave's multi-business support.

5. Cash flow forecasting
   "Analyze invoice payment patterns for the past 6 months, calculate average days to payment per customer, project cash inflows for next 30 days based on outstanding invoices."
   → Data-driven forecasting without spreadsheets.

🔗 The Real Power: Combining Tools

Claude orchestrates multi-step Wave workflows:

• list_businesses → list_invoices (per business) → create_invoice (for unbilled work)
• list_customers → filter duplicates → create_customer (with cleaned data)
• list_transactions → categorize → create_expense (with proper accounting codes)
• list_accounts → map to categories → generate financial reports

📦 What's Inside

8 GraphQL tools covering Wave's core accounting operations:

Tool	Purpose
list_businesses	Query all businesses in your Wave account
list_invoices	Browse invoices with pagination & filtering by business
create_invoice	Generate invoices with line items, terms, customer details
list_customers	Access customer directory per business
create_customer	Add new customers with contact & billing info
list_accounts	View chart of accounts (assets, liabilities, income, expenses)
list_transactions	Query transaction history with date ranges
create_expense	Record expenses with proper accounting codes & line items

All powered by Wave's GraphQL API with proper error handling, automatic pagination, and TypeScript types.

🚀 Quick Start

Option 1: Claude Desktop (Local)

1. Clone and build:

   git clone https://github.com/BusyBee3333/Wave-MCP-2026-Complete.git
   cd wave-mcp-2026-complete
   npm install
   npm run build
   

2. Get your Wave API token:

   • Go to Wave Developer Portal
   • Create an app or use "Manage Your Applications"
   • Generate an API token for your account
   • Copy the token (starts with gql_...)

3. Configure Claude Desktop:

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

   {
     "mcpServers": {
       "wave": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/wave-mcp-2026-complete/dist/index.js"],
         "env": {
           "WAVE_API_TOKEN": "gql_your_token_here"
         }
       }
     }
   }
   

4. Restart Claude Desktop
   Look for the 🔌 icon showing Wave tools are connected.

Option 2: Docker

docker build -t wave-mcp .
docker run \
  -e WAVE_API_TOKEN=gql_your_token_here \
  wave-mcp

🔐 Authentication

Wave uses OAuth 2.0 + API Tokens for GraphQL API access:

1. Register your application at Wave Developer Portal
2. Generate an API token (or OAuth credentials for production apps)
3. Use the token in environment variable WAVE_API_TOKEN

Token format: Starts with gql_ followed by alphanumeric string.

Scopes required:

• business:read — View business details
• invoice:read, invoice:write — Manage invoices
• customer:read, customer:write — Manage customers
• transaction:read, transaction:write — Access transactions & expenses

Token security: Tokens don't expire but can be revoked in your Wave settings. Store securely and never commit to version control.

🎯 Example Prompts

Once connected to Claude, use natural language for Wave accounting:

Multi-Business Operations

• "Show me all my Wave businesses with their currencies and whether they're personal or business accounts."
• "For my business 'Acme Consulting', list all open invoices sorted by due date."

Invoice Management

• "Create an invoice for business ID QnVz...X12 for customer ID Q3Vz...abc with 3 line items: Strategy Session $500, Implementation $2000, Support Plan $300/month. Due in 15 days."
• "List all invoices for my Toronto business from the past 30 days and show me which ones haven't been paid."
• "Generate a summary of all overdue invoices across all my businesses."

Customer Operations

• "Add a new customer to my main business: 'Global Tech Inc', email: billing@globaltech.com, address in New York NY, currency USD."
• "Show me all customers who have been invoiced in the last 6 months but have incomplete contact information."

Financial Tracking

• "List all expense accounts in my chart of accounts and group by type (assets, liabilities, income, expenses)."
• "Show me all transactions in my checking account from January 2024 and calculate the net cash flow."
• "Create an expense record for $127.50 from 'Office Supplies' account on 2024-01-15 with description 'Printer paper and toner'."

Analysis & Intelligence

• "Which customers have the longest average payment times? Show data from the past year."
• "Calculate total revenue per business for Q1 2024 and compare to Q4 2023."
• "Find all invoices that are 30+ days past due and draft reminder emails for each customer."

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn
• Wave account (free) with API access enabled

Local Setup

git clone https://github.com/BusyBee3333/Wave-MCP-2026-Complete.git
cd wave-mcp-2026-complete
npm install
cp .env.example .env
# Edit .env with your Wave API token
npm run build
npm run dev

Testing

npm test                  # Run all tests
npm run test:watch        # Watch mode
npm run test:coverage     # Coverage report

GraphQL Playground

Wave provides a GraphQL explorer for testing queries.

🐛 Troubleshooting

"Authentication failed" / GraphQL errors

• Token format: Ensure token starts with gql_ (not OAuth bearer tokens)
• Token validity: Check token hasn't been revoked in Wave settings
• Scopes: Verify your app has required permissions for the operations you're trying

"Business not found" / Empty results

• Get business IDs: Run list_businesses first to get valid business IDs
• Wave uses GraphQL IDs: IDs are base64-encoded strings like QnVzaW5lc3M6YWJjMTIz
• Multiple businesses: If you have multiple businesses, specify which one in each query

"Tools not appearing in Claude"

• Restart required: Always restart Claude Desktop after config changes
• Absolute paths: Use full paths in config (no ~/ shortcuts)
• Build check: Verify dist/index.js exists after running npm run build

GraphQL-specific issues

• Pagination: Wave uses cursor-based pagination; use pageInfo to navigate results
• Nested queries: Some operations require nested GraphQL selections (handled by this MCP server)
• Rate limiting: Wave has rate limits; the MCP server will throw errors if exceeded

📖 Resources

• Wave GraphQL API Docs — Official API reference
• Wave API Getting Started — Authentication & setup
• GraphQL Schema Explorer — Browse available queries & mutations
• Wave Changelog — API updates & deprecations
• MCP Protocol Specification — How MCP servers work
• Claude Desktop Documentation — Desktop app setup

🤝 Contributing

Contributions welcome! To add features:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/payment-tracking)
3. Commit your changes (git commit -m 'Add payment tracking tools')
4. Push to the branch (git push origin feature/payment-tracking)
5. Open a Pull Request

Ideas for contributions:

• Support for Wave's products/services catalog
• Sales tax calculation helpers
• Receipt image uploads via GraphQL mutations
• Recurring invoice templates
• Financial report generation (P&L, balance sheet)
• Multi-currency conversion helpers

📄 License

MIT License - see LICENSE for details

🙏 Credits

Built by MCPEngage — AI infrastructure for business software.

Want more MCP servers? Check out our full catalog covering 30+ business platforms.

---

Questions? Open an issue or join our Discord community.