QuickBooks Online MCP Server

Instructions

Implementation Reference

• src/index.ts:98-124 (schema)

  Tool definition with schema - defines the qbo_navigate tool structure including name, description, and inputSchema with domain validation (enum of allowed domains: customers, invoices, expenses, payments, reports)
  const navigateTool: Tool = { name: "qbo_navigate", description: "Navigate to a specific domain in QuickBooks Online. Call this first to select which area you want to work with. After navigation, domain-specific tools will be available.", inputSchema: { type: "object", properties: { domain: { type: "string", enum: [ "customers", "invoices", "expenses", "payments", "reports", ], description: `The domain to navigate to: - customers: ${domainDescriptions.customers} - invoices: ${domainDescriptions.invoices} - expenses: ${domainDescriptions.expenses} - payments: ${domainDescriptions.payments} - reports: ${domainDescriptions.reports}`, }, }, required: ["domain"], }, };
• src/index.ts:180-195 (handler)

  Tool handler implementation - processes the qbo_navigate request by updating server state to the selected domain, retrieving available tools for that domain, and returning a success message with the list of available tools
  if (name === "qbo_navigate") { const { domain } = args as { domain: Domain }; state.currentDomain = domain; const domainTools = getDomainTools(domain); const toolNames = domainTools.map((t) => t.name).join(", "); return { content: [ { type: "text", text: `Navigated to ${domain} domain. Available tools: ${toolNames}`, }, ], }; }
• src/index.ts:43-48 (schema)

  Domain type definition - TypeScript union type defining the five allowed domains for navigation (customers, invoices, expenses, payments, reports)
  type Domain = | "customers" | "invoices" | "expenses" | "payments" | "reports";
• src/index.ts:53-64 (schema)

  Domain descriptions metadata - provides human-readable descriptions for each domain used in the qbo_navigate tool's input schema to guide users on domain selection
  const domainDescriptions: Record<Domain, string> = { customers: "Customer management - list, get, create, and search customers", invoices: "Invoice management - list, get, create invoices and send them by email", expenses: "Expense tracking - list and view purchases and bills", payments: "Payment management - list, get, and create payments linked to invoices", reports: "Financial reports - profit & loss, balance sheet, aged receivables/payables, customer sales", };
• src/index.ts:157-170 (registration)

  Tool registration in ListTools handler - conditionally registers qbo_navigate when currentDomain is null (at root level), making it the entry point for the decision tree architecture
  server.setRequestHandler(ListToolsRequestSchema, async () => { const tools: Tool[] = []; if (state.currentDomain === null) { // At root - show navigation tool only tools.push(navigateTool); } else { // In a domain - show domain tools plus back navigation tools.push(backTool); tools.push(...getDomainTools(state.currentDomain)); } return { tools }; });