FreshBooks 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 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<sup>1</sup> created a command-line tool in Python, called 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 layer and new documentation, allowing LLM clients like Claude and Codex to work with invoicing using natural-language requests<sup>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, 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 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, 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 also requires an HTTPS redirect, typically provided by a temporary tunnel such as ngrok.
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 and MCP configuration documentation.
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 under the MIT license.
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. ↩ 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. ↩