$ show intuit/quickbooks-online-mcp-server
This repository implements a Model Context Protocol (MCP) server that exposes the QuickBooks Online API as tools for AI agents such as Claude Code. It provides 143 tools covering full CRUD and search operations across 29 entity types (Customer, Invoice, Bill, Vendor, Employee, Account, Item, JournalEntry, Deposit, Transfer, TimeActivity, etc.) and 11 financial reports (Balance Sheet, Profit & Loss, Cash Flow, Trial Balance, General Ledger, etc.). The architecture follows a clean separation between handler modules (wrapping the node-quickbooks library with OAuth authentication) and tool definitions (Zod schemas registered with the MCP server). A singleton QuickbooksClient manages OAuth 2.0 token refresh and persistence, while environment feature flags (QUICKBOOKS_DISABLE_WRITE/UPDATE/DELETE) suppress tool categories. The codebase is heavily tested with Jest (100% coverage enforced in CI) and uses modern TypeScript (ESM). It handles QBO-specific quirks such as automated sales tax (AST), sparse vs full updates, and fallback patterns (e.g., delete via void/inactive). Despite its broad coverage, the implementation is highly repetitive (87 handlers, 90 tools) with liberal use of `any` types and hand-rolled ambient declarations for missing upstream typings. The project is actively maintained with recent commits and detailed design documentation, though version numbers and test counts show minor drift between README and CHANGELOG. Overall, this is a comprehensive, production-grade integration that prioritizes completeness and correctness over elegance.
The LLM identified 4 files worth highlighting for reuse:
Normalizes different error shapes (Error objects, strings, unknown) into a consistent 'Error: message' string. Used across all handlers to produce uniform error responses. Isolated and generic — can be extracted directly into any TypeScript project.
Transforms a flat search parameter object into the nested criteria structure expected by node-quickbooks' list methods. Handles mapping of common parameters (name, email, phone, etc.) to QBO's internal field names. Reusable for any wrapper around QuickBooks-style search APIs.
Provides a generic function to register an MCP tool with its name, description, Zod schema, and handler. Separates the tool definition from the server bootstrap, making each tool self-contained and testable. This pattern can be reused in any MCP server implementation.
Defines the ToolResponse<T> generic type with { result: T, isError: boolean, error?: string } used uniformly across all handlers. This ensures a consistent API contract between the MCP server and AI clients. The pattern is simple but essential for maintainability.