Quickbooks-MCP-Martinez: Instructions file for Claude Code

QuickBooks MCP Server - Martinez Cleaning LLC

Purpose

MCP server connecting Claude to QuickBooks Online for Martinez Cleaning LLC financial operations. Enables natural language queries for invoices, bills, customers, vendors, and P&L reports.

Architecture

src/
├── tools/          # Individual tool modules (customers, invoices, bills, vendors, accounts, reports)
├── auth/           # OAuth client and QuickBooks API wrapper
├── types.ts        # Shared TypeScript interfaces
└── index.ts        # MCP server setup and tool registration

Bash Commands

• npm install - Install dependencies
• npm run build - Compile TypeScript to dist/
• npm run dev - Run locally in stdio mode with hot reload
• npm start - Run compiled server (stdio mode)
• TRANSPORT=http npm start - Run as HTTP server
• railway up - Deploy to Railway staging

Code Conventions

• TypeScript strict mode, ES modules
• Each tool in separate file under src/tools/
• All tools export: { name, description, handler }
• Async/await for all QBO API calls
• Errors: throw new QuickBooksError(message, code)
• Use zod for input validation schemas

Tool Pattern

Each tool exports: name, description (with inputSchema), handler

import { z } from "zod";
import type { QuickBooksClient } from "../auth/oauth.js";

const InputSchema = z.object({
  param: z.string().describe("Description")
}).strict();

export const toolName = {
  name: 'tool_name',
  description: {
    title: 'Tool Title',
    description: 'Clear description for Claude',
    inputSchema: InputSchema,
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true
    }
  },
  handler: async (params: z.infer<typeof InputSchema>, client: QuickBooksClient) => {
    const result = await client.queryCustomers({ limit: 100 });
    return {
      content: [{ type: 'text', text: JSON.stringify(result) }]
    };
  }
};

Environment Variables

Required:

• QUICKBOOKS_CLIENT_ID - From Intuit Developer Portal
• QUICKBOOKS_CLIENT_SECRET - From Intuit Developer Portal
• QUICKBOOKS_REFRESH_TOKEN - OAuth refresh token
• QUICKBOOKS_COMPANY_ID - QuickBooks realm ID
• QUICKBOOKS_ENVIRONMENT - "sandbox" or "production"