kaizen-qbo-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaizen CFO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# Kaizen QBO MCP Server
+
+MCP server that connects Claude Code, Cursor, and other AI tools to QuickBooks Online via the Kaizen API.
+
+## Quick Start
+
+```bash
+npm install @kaizencfo/qbo-mcp-server
+```
+
+Add to your Claude Code settings (`~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "kaizen-qbo": {
+      "command": "npx",
+      "args": ["@kaizencfo/qbo-mcp-server"],
+      "env": {
+        "KAIZEN_API_KEY": "kaizen_live_sk_..."
+      }
+    }
+  }
+}
+```
+
+Or create a `config.json` next to the server:
+
+```json
+{
+  "apiKey": "kaizen_live_sk_...",
+  "baseUrl": "https://api.kaizencfo.com"
+}
+```
+
+## Tools
+
+### Read
+| Tool | Description |
+|------|-------------|
+| `qbo_query` | Run SOQL queries (`SELECT * FROM Invoice WHERE ...`) |
+| `qbo_report` | Pull reports (P&L, Balance Sheet, Cash Flow, etc.) |
+| `qbo_get_entity` | Read a single entity by type + ID |
+| `qbo_get_attachments` | Get file attachments for an entity |
+
+### Write
+| Tool | Description |
+|------|-------------|
+| `qbo_create_invoice` | Create an invoice |
+| `qbo_create_journal_entry` | Create a journal entry |
+| `qbo_create_payment` | Create a payment |
+| `qbo_create_bill` | Create a bill |
+| `qbo_create_purchase` | Create a purchase/expense |
+| `qbo_update_entity` | Sparse-update any entity |
+| `qbo_void_invoice` | Void an invoice |
+
+## Examples
+
+Once configured, ask Claude:
+
+- "How much revenue did we do last month?"
+- "Show me all unpaid invoices over $1,000"
+- "Create a journal entry to reclassify $500 from Office Supplies to Marketing"
+- "Pull the P&L for Q1 2026"
+
+## Get an API Key
+
+Visit [kaizencfo.com](https://kaizencfo.com) to connect your QuickBooks Online account and get an API key.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "kaizen-qbo-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for QuickBooks Online — query, create, and manage QBO data via Claude Code or Cursor",
+  "type": "module",
+  "bin": {
+    "kaizen-qbo-mcp": "./server.mjs"
+  },
+  "main": "server.mjs",
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "keywords": ["mcp", "quickbooks", "qbo", "accounting", "claude", "cursor", "ai"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  }
+}

package/server.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Kaizen QBO MCP Server
+ *
+ * Thin MCP wrapper over the Kaizen REST API. Exposes QuickBooks Online
+ * data as tools for Claude Code, Cursor, and any MCP-compatible client.
+ *
+ * Tools:
+ *   qbo_query              — Run a SOQL query (SELECT ... FROM ...)
+ *   qbo_report             — Pull a QBO report (P&L, Balance Sheet, etc.)
+ *   qbo_get_entity         — Read a single entity by type + ID
+ *   qbo_get_attachments    — Get attachments for an entity
+ *   qbo_create_invoice     — Create an invoice
+ *   qbo_create_journal_entry — Create a journal entry
+ *   qbo_create_payment     — Create a payment
+ *   qbo_create_bill        — Create a bill
+ *   qbo_create_purchase    — Create a purchase
+ *   qbo_update_entity      — Update an entity (sparse update)
+ *   qbo_void_invoice       — Void an invoice
+ *
+ * Config:
+ *   Set KAIZEN_API_KEY env var, or create config.json next to this file:
+ *   { "apiKey": "kaizen_live_sk_...", "baseUrl": "https://api.kaizencfo.com" }
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFileSync } from "fs";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+function loadConfig() {
+  // Env vars take priority
+  const apiKey = process.env.KAIZEN_API_KEY;
+  const baseUrl = process.env.KAIZEN_API_URL || "https://api.kaizencfo.com";
+
+  if (apiKey) return { apiKey, baseUrl };
+
+  // Fall back to config.json
+  try {
+    const cfg = JSON.parse(readFileSync(resolve(__dirname, "config.json"), "utf-8"));
+    return {
+      apiKey: cfg.apiKey,
+      baseUrl: cfg.baseUrl || baseUrl,
+    };
+  } catch {
+    console.error("No KAIZEN_API_KEY env var and no config.json found.");
+    console.error("Set KAIZEN_API_KEY or create config.json with { \"apiKey\": \"kaizen_live_sk_...\" }");
+    process.exit(1);
+  }
+}
+
+const config = loadConfig();
+
+// ── API helper ──────────────────────────────────────────────────────────────
+
+async function api(path, { method = "GET", body } = {}) {
+  const url = `${config.baseUrl}${path}`;
+  const opts = {
+    method,
+    headers: {
+      "Authorization": `Bearer ${config.apiKey}`,
+      "Content-Type": "application/json",
+    },
+  };
+  if (body) opts.body = JSON.stringify(body);
+
+  const res = await fetch(url, opts);
+  const data = await res.json();
+
+  if (!data.ok) {
+    throw new Error(data.error?.message || `API error: ${res.status}`);
+  }
+  return data.data;
+}
+
+function resultText(data) {
+  return JSON.stringify(data, null, 2);
+}
+
+// ── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: "kaizen-qbo",
+  version: "0.1.0",
+});
+
+// ── Read Tools ──────────────────────────────────────────────────────────────
+
+server.tool(
+  "qbo_query",
+  "Run a SOQL query against QuickBooks Online. Examples: SELECT * FROM Invoice WHERE TxnDate >= '2026-01-01' MAXRESULTS 10",
+  {
+    query: z.string().describe("SOQL query string"),
+  },
+  async ({ query }) => {
+    const data = await api("/v1/query", { method: "POST", body: { query } });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_report",
+  "Pull a QBO report. Reports: ProfitAndLoss, BalanceSheet, CashFlow, TrialBalance, GeneralLedger, AgedReceivables, AgedPayables, CustomerIncome, VendorExpenses",
+  {
+    report: z.string().describe("Report name (e.g. ProfitAndLoss)"),
+    params: z.string().optional().describe("Query params (e.g. start_date=2026-01-01&end_date=2026-03-31&accounting_method=Accrual)"),
+  },
+  async ({ report, params }) => {
+    const qs = params ? `?${params}` : "";
+    const data = await api(`/v1/reports/${report}${qs}`);
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_get_entity",
+  "Read a single QBO entity by type and ID. Types: Invoice, Customer, Vendor, Bill, Payment, JournalEntry, Account, Item, Purchase, Estimate, CreditMemo, etc.",
+  {
+    type: z.string().describe("Entity type (e.g. Invoice, Customer)"),
+    id: z.string().describe("Entity ID"),
+  },
+  async ({ type, id }) => {
+    const data = await api(`/v1/entities/${type}/${id}`);
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_get_attachments",
+  "Get file attachments (check images, receipts, etc.) for a QBO entity",
+  {
+    type: z.string().describe("Entity type (e.g. Invoice, Bill, Purchase)"),
+    id: z.string().describe("Entity ID"),
+  },
+  async ({ type, id }) => {
+    const data = await api(`/v1/entities/${type}/${id}/attachments`);
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+// ── Write Tools ─────────────────────────────────────────────────────────────
+
+server.tool(
+  "qbo_create_invoice",
+  "Create a QBO invoice. Requires CustomerRef and at least one Line item.",
+  {
+    invoice: z.string().describe("Invoice JSON object (must include CustomerRef and Line array)"),
+  },
+  async ({ invoice }) => {
+    const data = await api("/v1/invoices", { method: "POST", body: JSON.parse(invoice) });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_create_journal_entry",
+  "Create a QBO journal entry. Requires Line array with JournalEntryLineDetail (PostingType, AccountRef).",
+  {
+    entry: z.string().describe("JournalEntry JSON object (must include Line array)"),
+  },
+  async ({ entry }) => {
+    const data = await api("/v1/journal-entries", { method: "POST", body: JSON.parse(entry) });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_create_payment",
+  "Create a QBO payment. Requires CustomerRef and TotalAmt.",
+  {
+    payment: z.string().describe("Payment JSON object"),
+  },
+  async ({ payment }) => {
+    const data = await api("/v1/payments", { method: "POST", body: JSON.parse(payment) });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_create_bill",
+  "Create a QBO bill. Requires VendorRef and Line array.",
+  {
+    bill: z.string().describe("Bill JSON object"),
+  },
+  async ({ bill }) => {
+    const data = await api("/v1/bills", { method: "POST", body: JSON.parse(bill) });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_create_purchase",
+  "Create a QBO purchase (expense/check). Requires AccountRef, PaymentType, and Line array.",
+  {
+    purchase: z.string().describe("Purchase JSON object"),
+  },
+  async ({ purchase }) => {
+    const data = await api("/v1/purchases", { method: "POST", body: JSON.parse(purchase) });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+// ── Update/Delete Tools ─────────────────────────────────────────────────────
+
+server.tool(
+  "qbo_update_entity",
+  "Update a QBO entity (sparse update). Must include Id and SyncToken from a prior read.",
+  {
+    type: z.string().describe("Entity type (e.g. Invoice, Customer)"),
+    id: z.string().describe("Entity ID"),
+    update: z.string().describe("JSON object with fields to update (must include SyncToken)"),
+  },
+  async ({ type, id, update }) => {
+    const data = await api(`/v1/entities/${type}/${id}`, {
+      method: "PATCH",
+      body: JSON.parse(update),
+    });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+server.tool(
+  "qbo_void_invoice",
+  "Void a QBO invoice by ID.",
+  {
+    id: z.string().describe("Invoice ID to void"),
+  },
+  async ({ id }) => {
+    const data = await api(`/v1/invoices/${id}/void`, { method: "POST" });
+    return { content: [{ type: "text", text: resultText(data) }] };
+  }
+);
+
+// ── Start ───────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);