QBO-MCP-TS

vespo92/QBO-MCP-TS

3.3

If you are the rightful owner of QBO-MCP-TS and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

QBOMCP-TS is a TypeScript-based server for QuickBooks Online, offering enhanced architecture and enterprise-grade features.

Tools
4
Resources
0
Prompts
0

QuickBooks Online MCP Server

A production-ready, modular Model Context Protocol (MCP) server for QuickBooks Online integration. Built with TypeScript, designed for accountants, with comprehensive automation features and real-time capabilities.

🚀 Features

Core Capabilities

  • ✅ Modular Architecture - Extensible tool and service system
  • ✅ Full CRUD Operations - Invoices, expenses, customers, payments
  • ✅ Financial Reporting - P&L, Balance Sheet, Cash Flow, AR/AP Aging
  • ✅ Real-Time Updates - SSE transport and QuickBooks webhooks
  • ✅ Workflow Automation - Rule-based automation engine
  • ✅ Multi-Company Support - Manage multiple QBO companies
  • ✅ Production-Ready - Comprehensive error handling, caching, rate limiting

Automation Features

  • 🔄 Recurring Invoices - Automated invoice generation (daily → yearly)
  • 📧 Payment Reminders - Smart follow-up sequences (4-tier system)
  • 🤖 Workflow Engine - Conditional rules and automated actions
  • 📊 Scheduled Reports - Automated report generation and distribution

Developer Experience

  • 🧪 Testing Infrastructure - Jest with comprehensive test utilities
  • 📝 TypeScript Strict Mode - Complete type safety
  • 🔍 Extensive Logging - Structured logging with context
  • 📚 Comprehensive Documentation - Examples and guides

📦 Installation

# Clone the repository
git clone https://github.com/vespo92/QBO-MCP-TS.git
cd QBO-MCP-TS

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your QuickBooks credentials

# Build
npm run build

# Run
npm start

🔧 Configuration

Environment Variables

# QuickBooks OAuth
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
COMPANY_ID=your_company_id
REFRESH_TOKEN=your_refresh_token

# Environment
QBO_ENVIRONMENT=sandbox  # or 'production'
NODE_ENV=development

# SSE Transport (optional)
SSE_PORT=3100
SSE_HOST=localhost

# Webhook Receiver (optional)
WEBHOOK_PORT=3200
WEBHOOK_VERIFIER_TOKEN=your_webhook_token

# Cache Settings
CACHE_TTL=300
CACHE_MAX_SIZE=100
ENABLE_CACHE=true

# API Settings
RETRY_ATTEMPTS=3
RETRY_DELAY=1000
TIMEOUT=30000
RATE_LIMIT=60

# Redis (optional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

🛠️ Available Tools

Invoice Management

  • get_invoices - Query invoices with filtering
  • create_invoice - Create invoices with line items
  • send_invoice - Email invoices to customers

Expense Management

  • get_expenses - Query expenses with filtering
  • create_expense - Create expenses with auto vendor/account lookup

Customer Management

  • get_customers - Query and search customers
  • get_customer_balance - Get balance details with overdue tracking

Financial Reporting

  • get_profit_loss - Profit & Loss statements
  • get_balance_sheet - Balance Sheet reports
  • get_cash_flow - Cash Flow statements
  • get_ar_aging - Accounts Receivable aging
  • get_ap_aging - Accounts Payable aging

Utilities

  • get_api_status - Server health and metrics

📖 Usage Examples

Create an Invoice

{
  "tool": "create_invoice",
  "params": {
    "customerName": "Acme Corp",
    "items": [
      {
        "description": "Web Design Services",
        "amount": 2500,
        "quantity": 1
      },
      {
        "description": "Hosting (1 year)",
        "amount": 600,
        "quantity": 1
      }
    ],
    "dueDate": "net 30",
    "emailToCustomer": true
  }
}

Query Overdue Invoices

{
  "tool": "get_invoices",
  "params": {
    "status": "overdue",
    "dateFrom": "this year",
    "dateTo": "today"
  }
}

Generate Profit & Loss Report

{
  "tool": "get_profit_loss",
  "params": {
    "startDate": "this quarter",
    "endDate": "today",
    "accountingMethod": "Accrual",
    "summarizeBy": "Month"
  }
}

🔄 Automation Setup

Recurring Invoices

import { automationService } from './services/automation.service';

const scheduleId = await automationService.createRecurringInvoice({
  customerId: '123',
  lineItems: [
    { description: 'Monthly Retainer', amount: 5000 }
  ],
  frequency: 'monthly',
  startDate: new Date('2025-01-01'),
  dueInDays: 30,
  autoSend: true
});

Workflow Rules

import { workflowService } from './services/workflow.service';

workflowService.addRule({
  id: 'auto-approve-small-expenses',
  name: 'Auto-approve small expenses',
  enabled: true,
  trigger: 'expense:submitted',
  conditions: [
    { field: 'TotalAmt', operator: 'lt', value: 100 },
    { field: 'category', operator: 'in', value: ['Office Supplies'] }
  ],
  actions: [
    { type: 'approve', notify: 'submitter' },
    { type: 'broadcast_event', eventType: 'expense:auto_approved' }
  ]
});

🌐 Real-Time Features

Server-Sent Events (SSE)

Start the SSE server for real-time client updates:

import { getSSETransport } from './transports/sse.transport';

const sse = getSSETransport();
await sse.start();

// Events automatically broadcast:
// - invoice:created, invoice:updated, invoice:paid
// - payment:received
// - expense:created
// - customer:created
// - report:ready
// - webhook:received

QuickBooks Webhooks

Receive real-time notifications from QuickBooks:

import { getWebhookReceiver } from './webhooks/receiver';

const webhooks = getWebhookReceiver({
  port: 3200,
  verifierToken: process.env.WEBHOOK_VERIFIER_TOKEN
});

// Register handlers
webhooks.on('invoice:create', async (data) => {
  console.log('Invoice created:', data.id);
  // Cache invalidation, notifications, etc.
});

await webhooks.start();

🏢 Multi-Company Support

Manage multiple QuickBooks companies:

import { multiCompanyService } from './services/multi-company.service';

// Add companies
await multiCompanyService.addCompany('company1', {
  name: 'Acme Corp',
  config: { /* QBO config */ }
});

await multiCompanyService.addCompany('company2', {
  name: 'XYZ Inc',
  config: { /* QBO config */ }
});

// Switch between companies
multiCompanyService.setActiveCompany('company1');
const invoices = await invoiceService.getInvoices();

multiCompanyService.setActiveCompany('company2');
const expenses = await expenseService.getExpenses();

💾 Redis Cache (Optional)

Enable Redis for distributed caching:

import { createRedisCacheService } from './services/cache-redis.service';

const cache = await createRedisCacheService({
  host: 'localhost',
  port: 6379,
  keyPrefix: 'qbo:',
  enableFallback: true  // Falls back to in-memory if Redis unavailable
});

// Automatically used by all services

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Writing Tests

import { createMockInvoice, MockQBOApiClient } from './test-utils';

describe('InvoiceService', () => {
  it('should create invoice', async () => {
    const mockClient = new MockQBOApiClient();
    const service = new InvoiceService(mockClient);

    const invoice = await service.createInvoice({
      customerName: 'Test Customer',
      lineItems: [{ description: 'Test', amount: 100 }]
    });

    expect(invoice.Id).toBeDefined();
  });
});

📊 Architecture

Service Layer

  • InvoiceService - Invoice operations and AR aging
  • ExpenseService - Expense management with vendor lookup
  • ReportService - 15+ financial reports with PDF export
  • CustomerService - Customer management and balance tracking
  • PaymentService - Payment recording and application
  • AutomationService - Recurring invoices and payment reminders
  • WorkflowService - Rule-based automation engine

Tool System

  • BaseTool - Abstract base with automatic validation
  • ToolRegistry - Auto-discovery and registration
  • Modular Structure - Each tool is self-contained

Transport Layer

  • SSE Transport - Real-time server-to-client streaming
  • Webhook Receiver - QuickBooks event notifications
  • STDIO Transport - Standard MCP communication

🔒 Security

  • ✅ OAuth 2.0 with automatic token refresh
  • ✅ HMAC-SHA256 webhook signature verification
  • ✅ Replay attack prevention
  • ✅ Input validation with Zod schemas
  • ✅ Sensitive data sanitization in logs
  • ✅ Rate limiting and request queuing

📈 Performance

  • ✅ Multi-tier caching (in-memory + optional Redis)
  • ✅ Request queuing to prevent API throttling
  • ✅ Exponential backoff retry logic
  • ✅ Batch operations where possible
  • ✅ Lazy service initialization

🐛 Error Handling

50+ predefined errors with actionable suggestions:

{
  code: 'QBO_AUTH_001',
  message: 'Your QuickBooks session has expired',
  suggestion: 'Refreshing authentication automatically...',
  recoverable: true,
  severity: 'warning'
}

Automatic retry for recoverable errors:

  • Token refresh failures
  • Rate limit exceeded
  • Network timeouts
  • Transient errors

📚 Documentation

  • FEATURES.md - Comprehensive feature documentation
  • ACCOUNTANT_NEEDS_RESEARCH.md - Accountant requirements research
  • IMPLEMENTATION_PLAN.md - Technical roadmap
  • API Examples - See examples/ directory

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new features
  4. Ensure all tests pass
  5. Submit a pull request

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

📞 Support

  • Issues: GitHub Issues
  • Documentation: See docs in repository
  • API Reference: See FEATURES.md

Made with ❤️ for accountants who want to automate their workflows