Quickbooks-MCP-Martinez: Skill for Claude Code

QuickBooks MCP Development

When to Use This Skill

Use this skill when:

• Adding new QuickBooks API tools
• Modifying existing tool schemas or handlers
• Debugging OAuth authentication issues
• Deploying to Railway or configuring Docker
• Understanding QuickBooks entity relationships

Tool Development Pattern

All tools follow this structure in src/tools/*.ts:

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

// Define input schema with Zod
const InputSchema = z.object({
  param_name: z.string().describe("Clear description for Claude"),
  limit: z.number().int().min(1).max(1000).default(100)
}).strict();

// Export tool object
export const toolName = {
  name: 'qbo_tool_name',
  description: {
    title: 'Human-Readable Tool Title',
    description: `Detailed description explaining:
- What the tool does
- Available parameters
- Return value structure
- Example use cases`,
    inputSchema: InputSchema,
    annotations: {
      readOnlyHint: true,        // true if no data modification
      destructiveHint: false,     // true if deletes/destroys data
      idempotentHint: true,       // true if same input = same output
      openWorldHint: true         // true if accesses external systems
    }
  },
  handler: async (params: z.infer<typeof InputSchema>, client: QuickBooksClient) => {
    try {
      // Call QuickBooks API via client
      const result = await client.queryCustomers({
        limit: params.limit
      });

      // Return MCP-compliant response
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
      };
    } catch (error: unknown) {
      const message = error instanceof Error ? error.message : "Unknown error";
      return {
        content: [{ type: 'text', text: `Error: ${message}` }],
        isError: true
      };
    }
  }
};

Adding a New Tool

Step 1: Create Tool File

Create src/tools/your-tool.ts with the pattern above.

Step 2: Register in Index

Add to src/index.ts:

import { yourTool } from "./tools/your-tool.js";

const tools = [
  // ... existing tools
  yourTool
];