freshbooks

This MCP server provides a Model Context Protocol integration for FreshBooks, enabling GenAI applications to interact with FreshBooks data and operations through a standardized MCP interface. The server exposes authentication methods, comprehensive API coverage for common FreshBooks resources, and robust error handling with retry logic. To use it, first install the package and configure your environment with your FreshBooks credentials. You can start the server from code by instantiating FreshbooksMCPServer and calling start(), or run it via the MCP runner using the uvx command with the package name. Once running, you can query clients, invoices, projects, and other supported resources through the MCP protocol, enabling seamless integration with AI-powered workflows. The server also supports asynchronous operation for improved performance in high-throughput scenarios and includes rate limiting to protect API usage.

Example usage (from code):

• from freshbooks_mcp import FreshbooksMCPServer
• server = FreshbooksMCPServer()
• server.start()

If you prefer command-line style execution, ensure your environment variables (e.g., FRESHBOOKS_API_TOKEN) are set, and run the MCP server using the uvx-based command as configured in mcp_config. This will expose the MCP endpoints the AI can query to perform actions like creating invoices, retrieving client data, or syncing project records.

Prerequisites:

• Python 3.8+ installed on your system
• pip available in PATH

Installation steps:

1. Install the package from PyPI: pip install freshbooks-mcp-server

2. (Optional) Install from source for development or latest changes: git clone https://github.com/LokiMCPUniverse/freshbooks-mcp-server.git cd freshbooks-mcp-server pip install -e .

3. Create a .env file or export required environment variables (see notes): FRESHBOOKS_API_TOKEN=your_token_here FRESHBOOKS_ACCOUNT_ID=your_account_id_if_required

4. Run the server (example using uvx invoked via MCP runner): uvx freshbooks-mcp-server

5. Verify the server is running by checking logs or making a test MCP request to the FreshBooks endpoints.

Notes and tips:

• The server relies on environment variables for FreshBooks authentication. Ensure these are securely stored and not committed to version control.
• If you rotate API credentials, update the environment variables and restart the server.
• Monitor rate limits and implement backoff strategies in your GenAI workflows to avoid throttling.
• If you encounter connection or authentication errors, double-check token scope and account association with FreshBooks.
• The configuration supports adding additional environment variables as needed by your deployment environment or FreshBooks API requirements.
• For development, you can clone the repository and install in editable mode to test changes quickly.