jake/wave-mcp-2026-complete
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rebrand to MCPEngage + deep Wave customization

Browse Source 
- Fix all MCPEngine → MCPEngage references
- Add Wave-specific Power Moves (5 small business accounting use cases)
- Correct tool count (8 GraphQL tools) with accurate descriptions
- Add GraphQL-specific documentation & API patterns
- Document Wave OAuth + GraphQL API token authentication
- Link to official Wave GraphQL API docs
- Update .env.example with WAVE_API_TOKEN format
- Add GraphQL troubleshooting & pagination notes
This commit is contained in:
Jake Shore 2026-02-02 06:59:42 -05:00
parent 8f64fc613b
commit c22ba91ed0
3 changed files with 139 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.env.example
View File

@ -1,2 +1,3 @@
# Wave API Credentials
WAVE_API_KEY=your-api-key-here
# Wave GraphQL API Token
# Get yours from: https://developer.waveapps.com
WAVE_API_TOKEN=gql_your_token_here

193
README.md
View File

@ -4,34 +4,61 @@
---
# 🚀 Wave MCP Server — 2026 Complete Version
# 📊 Wave MCP Server — AI-Native Small Business Accounting
## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire Wave workspace.** Instead of clicking through interfaces, you just *tell* it what you need.
**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
The AI can directly control your Wave account with natural language:
Real small business workflows you can automate instantly:
- **Smart automation** — Complex workflows in plain English
- **Data intelligence** — Query, analyze, and export your Wave data
- **Rapid operations** — Bulk actions that would take hours manually
- **Cross-platform integration** — Combine Wave with other tools seamlessly
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
AI can chain multiple Wave operations together:
Claude orchestrates multi-step Wave workflows:
- Query data → Filter results → Generate reports
- Search records → Update fields → Notify team
- Analyze metrics → Create tasks → Schedule follow-ups
- `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
**69 API tools** covering the entire Wave platform (Accounting).
**8 GraphQL tools** covering Wave's core accounting operations:
All with proper error handling, automatic authentication, and TypeScript types.
| 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
@ -45,12 +72,15 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build
```
2. **Get your Wave API credentials** (see Authentication section below)
2. **Get your Wave API token:**
- Go to [Wave Developer Portal](https://developer.waveapps.com/hc/en-us/articles/360019762711)
- 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 macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
@ -58,67 +88,89 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": {
"wave": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/wave-mcp/dist/index.js"],
"args": ["/ABSOLUTE/PATH/TO/wave-mcp-2026-complete/dist/index.js"],
"env": {
"WAVE_API_KEY": "your-api-key-here"
"WAVE_API_TOKEN": "gql_your_token_here"
}
}
}
}
```
4. **Restart Claude Desktop**
4. **Restart Claude Desktop**
Look for the 🔌 icon showing Wave tools are connected.
### Option 2: Deploy to Railway
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/wave-mcp)
1. Click the button above
2. Set your Wave API credentials in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
### Option 2: Docker
```bash
docker build -t wave-mcp .
docker run -p 3000:3000 \
-e WAVE_API_KEY=your-key \
docker run \
-e WAVE_API_TOKEN=gql_your_token_here \
wave-mcp
```
## 🔐 Authentication
See the official [Wave API documentation](https://docs.wave.com) for authentication details.
Wave uses **OAuth 2.0 + API Tokens** for GraphQL API access:
The MCP server handles token refresh automatically.
1. **Register your application** at [Wave Developer Portal](https://developer.waveapps.com)
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, you can use natural language. Examples:
Once connected to Claude, use natural language for Wave accounting:
- *"Show me recent activity in Wave"*
- *"Create a new record with these details..."*
- *"Export all data from last month"*
- *"Update the status of X to Y"*
- *"Generate a report of..."*
### 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 with API access
- Wave account (free) with API access enabled
### Setup
### Local Setup
```bash
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 credentials
# Edit .env with your Wave API token
npm run build
npm start
npm run dev
```
### Testing
@ -129,44 +181,69 @@ npm run test:watch # Watch mode
npm run test:coverage # Coverage report
```
### GraphQL Playground
Wave provides a [GraphQL explorer](https://developer.waveapps.com/hc/en-us/articles/360019968212-API-Explorer) for testing queries.
## 🐛 Troubleshooting
### "Authentication failed"
- Verify your API credentials are correct
- Check that your API key hasn't been revoked
- Ensure you have the necessary permissions
### "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 Claude Desktop after updating config
- Check that the path in `claude_desktop_config.json` is absolute
- Verify the build completed successfully (`dist/index.js` exists)
- **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 API Documentation](https://docs.wave.com)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop Documentation](https://claude.ai/desktop)
- **[Wave GraphQL API Docs](https://developer.waveapps.com/hc/en-us/articles/360019968212)** — Official API reference
- **[Wave API Getting Started](https://developer.waveapps.com/hc/en-us/articles/360019762711)** — Authentication & setup
- **[GraphQL Schema Explorer](https://developer.waveapps.com/hc/en-us/articles/360020154331)** — Browse available queries & mutations
- **[Wave Changelog](https://developer.waveapps.com/hc/en-us/sections/360003012132-Changelog)** — API updates & deprecations
- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** — How MCP servers work
- **[Claude Desktop Documentation](https://claude.ai/desktop)** — Desktop app setup
## 🤝 Contributing
Contributions are welcome! Please:
Contributions welcome! To add features:
1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`)
3. Commit your changes (`git commit -m 'Add amazing tool'`)
4. Push to the branch (`git push origin feature/amazing-tool`)
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](LICENSE) for details
## 🙏 Credits
Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software.
Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software.
Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms.
---
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine).
**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage).

2
package.json
View File

@ -4,7 +4,7 @@
"description": "MCP server for Wave API - 2026 Complete Version",
"type": "module",
"main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>",
"author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT",
"repository": {
"type": "git",