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 };
  });