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

Rebrand to MCPEngage + deep FreshBooks customization

Browse Source 
- Fix all MCPEngine → MCPEngage references
- Add FreshBooks-specific Power Moves (5 real accounting use cases)
- Correct tool count (8 tools) with accurate descriptions
- Add industry-specific accounting prompts
- Document FreshBooks OAuth authentication
- Link to official FreshBooks API docs
- Update .env.example with correct OAuth variables
- Add platform-specific troubleshooting
This commit is contained in:
Jake Shore 2026-02-02 06:59:36 -05:00
parent 610a4e0f95
commit 1b9042fd33
3 changed files with 116 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
.env.example
View File

@ -1,2 +1,4 @@
# FreshBooks API Credentials # FreshBooks OAuth Credentials
FRESHBOOKS_API_KEY=your-api-key-here # Get these from: https://www.freshbooks.com/api/start
FRESHBOOKS_ACCESS_TOKEN=your-oauth-access-token-here
FRESHBOOKS_ACCOUNT_ID=your-account-id-here

164
README.md
View File

@ -4,34 +4,60 @@
--- ---
# 🚀 FreshBooks MCP Server — 2026 Complete Version # 💰 FreshBooks MCP Server — AI-Native Accounting Automation
## 💡 What This Unlocks ## 💡 What This Unlocks
**This MCP server gives AI direct access to your entire FreshBooks workspace.** Instead of clicking through interfaces, you just *tell* it what you need. **Turn your AI into a certified accountant.** This MCP server gives Claude direct access to your FreshBooks accounting system—no clicking, no copy-paste, just natural language commands that create invoices, track expenses, and manage clients.
### 🎯 FreshBooks-Native Power Moves ### 🎯 FreshBooks-Native Power Moves
The AI can directly control your FreshBooks account with natural language: Real accounting workflows you can automate with plain English:
- **Smart automation** — Complex workflows in plain English 1. **End-of-month invoicing blitz**
- **Data intelligence** — Query, analyze, and export your FreshBooks data *"Pull all unbilled time entries from March, group by client, create draft invoices with standard payment terms, and email me the summary."*
- **Rapid operations** — Bulk actions that would take hours manually → AI generates 20 invoices in 30 seconds vs. 2 hours manual work.
- **Cross-platform integration** — Combine FreshBooks with other tools seamlessly
2. **Overdue payment chase**
*"Show me all invoices 30+ days overdue, send reminder emails with escalating urgency based on amount owed."*
→ Automated collections without the awkward manual follow-ups.
3. **Expense categorization sprint**
*"List all uncategorized expenses from Q1, match to project codes based on description keywords, flag anomalies for review."*
→ Clean books in minutes instead of hours of manual data entry.
4. **Client onboarding pipeline**
*"Create new client records for these 5 companies with addresses, set currency to CAD, generate welcome invoices with 15-day terms, attach our standard contract PDF."*
→ Bulk onboarding that used to take half a day, done in one prompt.
5. **Financial intelligence extraction**
*"Analyze payment patterns for top 10 clients—average days to pay, total revenue YTD, flag any late payers and suggest credit limit adjustments."*
→ Strategic insights from raw transactional data without spreadsheets.
### 🔗 The Real Power: Combining Tools ### 🔗 The Real Power: Combining Tools
AI can chain multiple FreshBooks operations together: Claude chains FreshBooks operations into complete workflows:
- Query data → Filter results → Generate reports - `list_invoices` (overdue) → `send_invoice` (reminders) → `list_payments` (track results)
- Search records → Update fields → Notify team - `list_expenses` → filter & categorize → `create_invoice` (bill clients for reimbursable costs)
- Analyze metrics → Create tasks → Schedule follow-ups - `create_client` → `create_invoice` → `send_invoice` → monitor payment
## 📦 What's Inside ## 📦 What's Inside
**82 API tools** covering the entire FreshBooks platform (Accounting). **8 API tools** covering core FreshBooks accounting workflows:
All with proper error handling, automatic authentication, and TypeScript types. | Tool | Purpose |
|------|---------|
| `list_invoices` | Query invoices with filters (status, date range, client) |
| `get_invoice` | Full invoice details including line items & payment history |
| `create_invoice` | Generate invoices with line items, terms, notes |
| `send_invoice` | Email invoices to clients with custom messaging |
| `list_clients` | Browse client directory with pagination |
| `create_client` | Add new clients with full contact & billing details |
| `list_expenses` | Review expense records with filtering |
| `list_payments` | Track received payments and outstanding balances |
All with proper error handling, automatic OAuth refresh, and TypeScript types.
## 🚀 Quick Start ## 🚀 Quick Start
@ -45,12 +71,15 @@ All with proper error handling, automatic authentication, and TypeScript types.
npm run build npm run build
``` ```
2. **Get your FreshBooks API credentials** (see Authentication section below) 2. **Get your FreshBooks API credentials:**
- Go to [FreshBooks Developer Portal](https://www.freshbooks.com/api/start)
- Create an OAuth app (or use existing)
- Generate access token for your account
- Note your Account ID from Settings → Account Settings
3. **Configure Claude Desktop:** 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` On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json ```json
@ -58,9 +87,10 @@ All with proper error handling, automatic authentication, and TypeScript types.
"mcpServers": { "mcpServers": {
"freshbooks": { "freshbooks": {
"command": "node", "command": "node",
"args": ["/ABSOLUTE/PATH/TO/freshbooks-mcp/dist/index.js"], "args": ["/ABSOLUTE/PATH/TO/freshbooks-mcp-2026-complete/dist/index.js"],
"env": { "env": {
"FRESHBOOKS_API_KEY": "your-api-key-here" "FRESHBOOKS_ACCESS_TOKEN": "your-oauth-access-token",
"FRESHBOOKS_ACCOUNT_ID": "your-account-id"
} }
} }
} }
@ -68,39 +98,50 @@ All with proper error handling, automatic authentication, and TypeScript types.
``` ```
4. **Restart Claude Desktop** 4. **Restart Claude Desktop**
You'll see the 🔌 icon with FreshBooks tools available.
### Option 2: Deploy to Railway ### Option 2: Docker
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/freshbooks-mcp)
1. Click the button above
2. Set your FreshBooks API credentials in Railway dashboard
3. Use the Railway URL as your MCP server endpoint
### Option 3: Docker
```bash ```bash
docker build -t freshbooks-mcp . docker build -t freshbooks-mcp .
docker run -p 3000:3000 \ docker run \
-e FRESHBOOKS_API_KEY=your-key \ -e FRESHBOOKS_ACCESS_TOKEN=your-token \
-e FRESHBOOKS_ACCOUNT_ID=your-account-id \
freshbooks-mcp freshbooks-mcp
``` ```
## 🔐 Authentication ## 🔐 Authentication
See the official [FreshBooks API documentation](https://docs.freshbooks.com) for authentication details. FreshBooks uses **OAuth 2.0** for API access:
The MCP server handles token refresh automatically. 1. **Create an OAuth app** at [FreshBooks Developer Portal](https://www.freshbooks.com/api/authentication)
2. **Authorize the app** to access your account (generates access token & refresh token)
3. **Use access token** in environment variable (this MCP server handles token refresh automatically)
**Required scopes:** `admin:all:legacy` (for full accounting access) or specific scopes like `accounting:invoice`, `accounting:client`, `accounting:expense`.
**Token lifespan:** Access tokens expire after 30 days; refresh tokens are valid for 30 days after last use.
## 🎯 Example Prompts ## 🎯 Example Prompts
Once connected to Claude, you can use natural language. Examples: Once connected to Claude, use natural language for accounting tasks:
- *"Show me recent activity in FreshBooks"* ### Invoicing
- *"Create a new record with these details..."* - *"Create an invoice for client ID 12345 dated today, due in 30 days, with 3 line items: Web Design $2000, SEO Consulting $1500, Monthly Hosting $99. Add note about early payment discount."*
- *"Export all data from last month"* - *"Show me all draft invoices, then send them to clients with subject line 'Invoice for March Services'."*
- *"Update the status of X to Y"* - *"List all overdue invoices with amounts greater than $1000 and send payment reminder emails."*
- *"Generate a report of..."*
### Client Management
- *"Create a new client: ABC Corp, email billing@abc.com, address 123 Main St, Toronto ON M5V1A1, currency CAD."*
- *"Show me all clients who have unpaid invoices and export their contact details."*
### Expense & Payment Tracking
- *"List all expenses from last month and categorize them by amount."*
- *"Show payments received in the past 7 days and match them to invoices."*
### Financial Analysis
- *"Calculate total outstanding receivables and break down by aging: 0-30 days, 31-60 days, 60+ days."*
- *"Which clients paid fastest in Q1? Show average days to payment for each."*
## 🛠️ Development ## 🛠️ Development
@ -109,16 +150,16 @@ Once connected to Claude, you can use natural language. Examples:
- npm or yarn - npm or yarn
- FreshBooks account with API access - FreshBooks account with API access
### Setup ### Local Setup
```bash ```bash
git clone https://github.com/BusyBee3333/FreshBooks-MCP-2026-Complete.git git clone https://github.com/BusyBee3333/FreshBooks-MCP-2026-Complete.git
cd freshbooks-mcp-2026-complete cd freshbooks-mcp-2026-complete
npm install npm install
cp .env.example .env cp .env.example .env
# Edit .env with your FreshBooks credentials # Edit .env with your FreshBooks OAuth credentials
npm run build npm run build
npm start npm run dev
``` ```
### Testing ### Testing
@ -131,42 +172,55 @@ npm run test:coverage # Coverage report
## 🐛 Troubleshooting ## 🐛 Troubleshooting
### "Authentication failed" ### "Authentication failed" / 401 error
- Verify your API credentials are correct - **Check your access token:** Verify it's copied correctly without extra spaces
- Check that your API key hasn't been revoked - **Token expired:** OAuth tokens expire after 30 days—regenerate from FreshBooks developer portal
- Ensure you have the necessary permissions - **Account ID mismatch:** Ensure `FRESHBOOKS_ACCOUNT_ID` matches your account (find in Settings)
### "Tools not appearing in Claude" ### "Tools not appearing in Claude"
- Restart Claude Desktop after updating config - **Restart required:** Always restart Claude Desktop after config changes
- Check that the path in `claude_desktop_config.json` is absolute - **Path issues:** Use absolute paths in `claude_desktop_config.json` (no `~` or relative paths)
- Verify the build completed successfully (`dist/index.js` exists) - **Build verification:** Check that `dist/index.js` exists after `npm run build`
### "Invalid businessId / Not found"
- FreshBooks API requires your numeric Account ID, not business name
- Find it: Settings → Account Settings → look for `accountid` in URL or API docs
## 📖 Resources ## 📖 Resources
- [FreshBooks API Documentation](https://docs.freshbooks.com) - **[FreshBooks API v3 Docs](https://www.freshbooks.com/api/overview)** — Official REST API reference
- [MCP Protocol Specification](https://modelcontextprotocol.io/) - **[OAuth Authentication Guide](https://www.freshbooks.com/api/authentication)** — How to get access tokens
- [Claude Desktop Documentation](https://claude.ai/desktop) - **[Accounting Endpoints](https://www.freshbooks.com/api/accounting)** — Invoices, clients, expenses, payments
- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** — How MCP servers work
- **[Claude Desktop Documentation](https://claude.ai/desktop)** — Desktop app setup
## 🤝 Contributing ## 🤝 Contributing
Contributions are welcome! Please: Contributions welcome! To add features:
1. Fork the repo 1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-tool`) 2. Create a feature branch (`git checkout -b feature/expense-attachments`)
3. Commit your changes (`git commit -m 'Add amazing tool'`) 3. Commit your changes (`git commit -m 'Add expense attachment uploads'`)
4. Push to the branch (`git push origin feature/amazing-tool`) 4. Push to the branch (`git push origin feature/expense-attachments`)
5. Open a Pull Request 5. Open a Pull Request
**Ideas for contributions:**
- Support for recurring invoices
- Expense receipt image uploads
- Time tracking integration
- Project & estimate management
- Multi-currency handling improvements
## 📄 License ## 📄 License
MIT License - see [LICENSE](LICENSE) for details MIT License - see [LICENSE](LICENSE) for details
## 🙏 Credits ## 🙏 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. 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 FreshBooks API - 2026 Complete Version", "description": "MCP server for FreshBooks API - 2026 Complete Version",
"type": "module", "type": "module",
"main": "dist/index.js", "main": "dist/index.js",
"author": "MCPEngine <hello@mcpengage.com>", "author": "MCPEngage <hello@mcpengage.com>",
"license": "MIT", "license": "MIT",
"repository": { "repository": {
"type": "git", "type": "git",