FreshBooks Tools - CLI and LLM integration with FreshBooks invoicing

Andrew Lombardi released FreshBooks Tools, an open-source Python command-line tool that exposes FreshBooks time tracking, projects, invoices, expenses and financial reports through commands such as `fb time add --hours 2 --project acme --service dev`. The project now includes an MCP server layer, contributed by the article's author, that lets LLM clients like Claude and Codex file time and query invoicing data via natural-language requests, including a `time_habits` tool that infers which services are commonly tied to each project. The MCP tools reuse the same underlying functionality as the CLI, so the same operations can be invoked from a terminal or an assistant without two separate implementations.

FreshBooks https://www.freshbooks.com/ is a time tracking/invoice management site for contractors, something I've been using for years. Yet using it is a context switch: I go from my IDE https://bytecode.news/factoids/ide or my command line to a website, and filing time involves selecting clientele, project, entry type, and so on. FreshBooks is done well, and it works, but it's a break from flow . They do, however, provide an API for external tools, so the possibility is there to create something that fits: Andrew Lombardi https://mysticcoders.com/ <sup 1 fn-1 </sup created a command-line tool in Python https://www.python.org/ , called FreshBooks Tools https://github.com/mysticcoders/freshbooks-tools , providing access to time tracking, projects, invoices, expenses, and financial reports, all without having to use the FreshBooks web application itself. It works - and "working" is better than "not working," obviously. But now it has an MCP https://modelcontextprotocol.io layer and new documentation, allowing LLM clients like Claude and Codex to work with invoicing using natural-language requests<sup 2 fn-2 </sup . Just in case you don't read my awesome footnotes, I contributed the MCP layer and some of the documentation. Open Source, folks, at your service and your family's. What It Does The CLI exposes a number of FreshBooks operations, including: - Time tracking: Log time, review entries, manage project and service aliases. - Projects: List projects and associated services. - Invoices and receivables: Examine invoices, overdue balances, and accounts receivable. - Reporting: Review revenue, expenses, unbilled time, and financial information. - Exports: Retrieve data for further analysis. For example: fb projects list fb time add --hours 2 --project acme --service dev fb invoices list --status overdue fb reports ar-aging The CLI supports aliases for commonly used projects and services, so once a default is configured, adding two hours can be as simple as: fb time add --hours 2 If there's already a matching unbilled entry for the day, the tool adds the hours to that entry rather than necessarily creating another one. There is, of course, an option to add a new entry instead of modifying one that already exists. This makes the CLI useful for ordinary terminal workflows, scripts, and automation, without involving an LLM at all. MCP Support The project also provides an MCP server, exposing FreshBooks functionality to compatible LLM clients. Here's an actual example of how I use it: Hey, add two hours to acme. And two hours get added to the appropriate FreshBooks project for today. I don't open a browser, find the project, select the service, or manually enter the time: I'm working on the project, I mention the time I've spent working on it, and it's done. If a request is ambiguous, the possibilities come back to the model and it asks rather than guesses; errors say what to do next; and the whole thing is built to interrupt as little as possible, so working on a project doesn't mean stopping to think about billing. The integration includes a time habits tool that examines historical entries to determine which services are commonly associated with each project. This provides context for the assistant when a request doesn't specify every detail. The MCP tools use the same underlying functionality as the CLI. The LLM handles the conversational interface; the application handles the FreshBooks operations. The result is a system where the same functionality can be invoked directly from a terminal or through an assistant, without maintaining two separate implementations. The Documentation Documentation is done via Diátaxis https://diataxis.fr/ , which lays content out along four quadrants: how-tos, tutorials, references, and explanations - with the information being based largely on questions asked and answered in the process of development. "How do I file time?" gets its own page https://github.com/mysticcoders/freshbooks-tools/blob/main/docs/how-to/log-time-with-aliases.md in the how-to docs, as do questions like "How do I use the CLI" or "How do I connect an LLM to this?," along with explanations for why installation works the way it does. The reference is generated , by using scripts/gen reference.py so there's no drifting from what's actually implemented; if functionality changes, the interaction notes change as well. It's designed to not be able to drift. Installation FreshBooks Tools requires Python 3.11 or newer, uv https://docs.astral.sh/uv/ , and a FreshBooks account. To install from the repository: git clone https://github.com/mysticcoders/freshbooks-tools.git cd freshbooks-tools uv sync cp .env.example .env FreshBooks uses OAuth, so you'll need to create an application through the FreshBooks developer portal and configure its credentials in .env . Initial authentication https://bytecode.news/factoids/authentication also requires an HTTPS redirect, typically provided by a temporary tunnel such as ngrok https://ngrok.com . Once configured: uv run fb auth login uv run fb projects list For a global installation: uv tool install . fb auth setup .env To register the MCP server with Claude Code: claude mcp add --scope user freshbooks -- fb mcp Other clients, including Codex, are supported. The repository includes getting-started instructions https://github.com/mysticcoders/freshbooks-tools/blob/main/docs/tutorials/getting-started.md and MCP configuration documentation https://github.com/mysticcoders/freshbooks-tools/blob/main/docs/how-to/connect-an-llm.md . The Point MCP isn't a requirement for using FreshBooks Tools. It's another interface to functionality that already exists. The CLI is useful on its own. MCP makes it possible to incorporate that functionality into conversational workflows without forcing an LLM to understand the details of the FreshBooks API. Andrew built a useful tool and made it available. I needed a little more from it, contributed the changes, and he accepted them. Now everyone can use the additions. The project is available on GitHub https://github.com/mysticcoders/freshbooks-tools under the MIT license. 1. Andrew is, as I've written before, a friend and a co-author and a co-worker; a lot of my Freshbooks invoices have gone to him. ↩ fnref-1 2. It works almost exactly how I would like it to work, because I guided the development of the MCP layer and the documentation, although I used an LLM to contribute as well. ↩ fnref-2