README.md•2.85 kB
# FreshBooks MCP Server
Automate your FreshBooks invoicing and time tracking through Claude. This MCP server provides seamless integration with FreshBooks while using Xano as the authentication backend.
## 🚀 Features
- **Send Saturday Invoices** - Automate your weekly billing with one command
- **List Invoices** - View and filter invoices by status
- **Log Time Entries** - Track billable hours directly from Claude
- **Revenue Reports** - Get financial insights instantly
- **Secure Authentication** - Uses your existing Xano account for auth
## 🛠️ Setup
### 1. Get Your FreshBooks Account ID
1. Log into FreshBooks
2. Look at your URL: `https://my.freshbooks.com/#/accounting/<ACCOUNT_ID>/dashboard`
3. Copy the account ID
### 2. Configure the Server
Edit `wrangler.jsonc`:
```jsonc
{
"vars": {
"FRESHBOOKS_ACCOUNT_ID": "your-account-id-here"
}
}
```
### 3. Deploy to Cloudflare
```bash
npm install
npx wrangler deploy
```
### 4. Connect FreshBooks on mcp.snappy.ai
1. Visit [mcp.snappy.ai](https://mcp.snappy.ai)
2. Go to Integrations
3. Click "Connect FreshBooks"
4. Complete OAuth flow
### 5. Add to Claude Desktop
Edit your Claude Desktop config:
```json
{
"mcpServers": {
"freshbooks": {
"command": "npx",
"args": [
"mcp-remote",
"connect",
"wss://freshbooks-mcp-server.your-subdomain.workers.dev/mcp"
]
}
}
}
```
## 📋 Available Tools
### `freshbooks_list_invoices`
List all invoices with optional status filter
- Parameters: `status` (optional), `page` (optional)
### `freshbooks_send_saturday_invoices`
Send all draft invoices (perfect for Saturday billing)
- Parameters: `dry_run` (default: true for preview)
### `freshbooks_log_time`
Log billable hours for a client
- Parameters: `client_name`, `hours`, `description`, `date` (optional)
### `freshbooks_revenue_report`
Get revenue summary for a date range
- Parameters: `start_date` (optional), `end_date` (optional)
### `debug_auth_status`
Check connection status for both Xano and FreshBooks
## 🎯 Usage Examples
```
You: "Send my Saturday invoices"
Claude: [Shows preview of 3 draft invoices]
You: "Actually send them"
Claude: ✅ Sent 3 invoices totaling $4,250
You: "Log 2 hours for PVM project today"
Claude: ⏱️ Time entry created for PVM
```
## 🏗️ Architecture
- **Authentication**: Xano (existing user management)
- **API Integration**: FreshBooks (stored in Xano user profile)
- **Deployment**: Cloudflare Workers
- **OAuth Management**: mcp.snappy.ai
## 🔒 Security
- FreshBooks credentials stored securely in your Xano account
- No direct OAuth in the MCP server
- User-scoped access only
- Tokens auto-refresh as needed
## 🤝 Contributing
This is part of the Snappy MCP ecosystem. Visit [mcp.snappy.ai](https://mcp.snappy.ai) to learn more.
## 📝 License
MIT