From 1b9042fd331ec6f741f130d8eacbd4d339c2b537 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:59:36 -0500 Subject: [PATCH] Rebrand to MCPEngage + deep FreshBooks customization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .env.example | 6 +- README.md | 168 ++++++++++++++++++++++++++++++++++----------------- package.json | 2 +- 3 files changed, 116 insertions(+), 60 deletions(-) diff --git a/.env.example b/.env.example index aaad6b4..3539380 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,4 @@ -# FreshBooks API Credentials -FRESHBOOKS_API_KEY=your-api-key-here +# FreshBooks OAuth Credentials +# Get these from: https://www.freshbooks.com/api/start +FRESHBOOKS_ACCESS_TOKEN=your-oauth-access-token-here +FRESHBOOKS_ACCOUNT_ID=your-account-id-here diff --git a/README.md b/README.md index 3cf615a..f7bc4c8 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,60 @@ --- -# πŸš€ FreshBooks MCP Server β€” 2026 Complete Version +# πŸ’° FreshBooks MCP Server β€” AI-Native Accounting Automation ## πŸ’‘ 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 -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 -- **Data intelligence** β€” Query, analyze, and export your FreshBooks data -- **Rapid operations** β€” Bulk actions that would take hours manually -- **Cross-platform integration** β€” Combine FreshBooks with other tools seamlessly +1. **End-of-month invoicing blitz** + *"Pull all unbilled time entries from March, group by client, create draft invoices with standard payment terms, and email me the summary."* + β†’ AI generates 20 invoices in 30 seconds vs. 2 hours manual work. + +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 -AI can chain multiple FreshBooks operations together: +Claude chains FreshBooks operations into complete workflows: -- Query data β†’ Filter results β†’ Generate reports -- Search records β†’ Update fields β†’ Notify team -- Analyze metrics β†’ Create tasks β†’ Schedule follow-ups +- `list_invoices` (overdue) β†’ `send_invoice` (reminders) β†’ `list_payments` (track results) +- `list_expenses` β†’ filter & categorize β†’ `create_invoice` (bill clients for reimbursable costs) +- `create_client` β†’ `create_invoice` β†’ `send_invoice` β†’ monitor payment ## πŸ“¦ 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 @@ -45,12 +71,15 @@ All with proper error handling, automatic authentication, and TypeScript types. 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:** - 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,49 +87,61 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "freshbooks": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/freshbooks-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/freshbooks-mcp-2026-complete/dist/index.js"], "env": { - "FRESHBOOKS_API_KEY": "your-api-key-here" + "FRESHBOOKS_ACCESS_TOKEN": "your-oauth-access-token", + "FRESHBOOKS_ACCOUNT_ID": "your-account-id" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** + You'll see the πŸ”Œ icon with FreshBooks tools available. -### Option 2: Deploy to Railway - -[![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 +### Option 2: Docker ```bash docker build -t freshbooks-mcp . -docker run -p 3000:3000 \ - -e FRESHBOOKS_API_KEY=your-key \ +docker run \ + -e FRESHBOOKS_ACCESS_TOKEN=your-token \ + -e FRESHBOOKS_ACCOUNT_ID=your-account-id \ freshbooks-mcp ``` ## πŸ” 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 -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"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +### Invoicing +- *"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."* +- *"Show me all draft invoices, then send them to clients with subject line 'Invoice for March Services'."* +- *"List all overdue invoices with amounts greater than $1000 and send payment reminder emails."* + +### 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 @@ -109,16 +150,16 @@ Once connected to Claude, you can use natural language. Examples: - npm or yarn - FreshBooks account with API access -### Setup +### Local Setup ```bash git clone https://github.com/BusyBee3333/FreshBooks-MCP-2026-Complete.git cd freshbooks-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your FreshBooks credentials +# Edit .env with your FreshBooks OAuth credentials npm run build -npm start +npm run dev ``` ### Testing @@ -131,42 +172,55 @@ npm run test:coverage # Coverage report ## πŸ› 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" / 401 error +- **Check your access token:** Verify it's copied correctly without extra spaces +- **Token expired:** OAuth tokens expire after 30 daysβ€”regenerate from FreshBooks developer portal +- **Account ID mismatch:** Ensure `FRESHBOOKS_ACCOUNT_ID` matches your account (find in Settings) ### "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 +- **Path issues:** Use absolute paths in `claude_desktop_config.json` (no `~` or relative paths) +- **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 -- [FreshBooks API Documentation](https://docs.freshbooks.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[FreshBooks API v3 Docs](https://www.freshbooks.com/api/overview)** β€” Official REST API reference +- **[OAuth Authentication Guide](https://www.freshbooks.com/api/authentication)** β€” How to get access tokens +- **[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 -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/expense-attachments`) +3. Commit your changes (`git commit -m 'Add expense attachment uploads'`) +4. Push to the branch (`git push origin feature/expense-attachments`) 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 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). diff --git a/package.json b/package.json index 4f455ee..58ccb80 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for FreshBooks API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",