# KiMagic

> Connect QuickBooks Online to AI. Reports, insights, and automation for your books.

KiMagic is an MCP server and web app that gives AI assistants access to QuickBooks Online data. Users sign in with their Intuit account, connect QBO companies, and use AI to query financials, generate reports, manage customers, create invoices, and more.

## App Structure

- Dashboard: https://kimagic.app/dashboard — cash position, AR/AP, recent activity
- Explorer: https://kimagic.app/explorer — interactive SQL + raw API query tool
- Reports: https://kimagic.app/reports — scheduled and custom reports
- Settings: https://kimagic.app/settings — account management, connected companies

## MCP Endpoint

- URL: https://kimagic.app/mcp
- Transport: Streamable HTTP (JSON-RPC 2.0)
- Auth: Bearer JWT (see "Getting a Token" below)

## Session & Auth

- GET /api/auth/me — returns current user info and connected QBO realms if authenticated
- GET /api/session/token — exchange active browser session cookie for a short-lived JWT
- POST /api/session/token — scoped exchange: `{ "realm_id": "...", "ttl_minutes": 30 }`
- POST /api/session/revoke — revoke a JWT: `{ "token": "eyJ..." }`

## Getting a Token (Browser Sessions)

If the user is already signed in, obtain a short-lived JWT without manual setup:

  GET /api/session/token → { "token": "eyJ...", "expires_at": "...", "realm_ids": [...], "user": "..." }

Use the returned token as: Authorization: Bearer <token>

## Multi-Company

Users can connect multiple QBO companies. Use `list_connections` to see available realms. One company is marked as default.

- Connected realms listed in GET /api/auth/me under `connections`
- Each connection has: realmId, companyName, environment, isDefault

## Errors

All errors return JSON: `{ "error": true, "statusCode": 401, "statusMessage": "...", "message": "..." }`

- 401 = not authenticated or expired token
- 403 = no QBO connection for that realm
- 429 = QBO rate limit hit (wait and retry, avoid parallel calls)
- 500 = server error (check message for details)

## Rate Limiting

QBO enforces rate limits. Avoid running many tool calls in parallel against the same QBO company. If you hit a 429, wait a few seconds and retry. AI analysis tools (cash_flow_forecast, month_end_checklist, find_anomalies) make multiple QBO calls internally and may return partial results under heavy load.

## Tools (exact names as returned by tools/list)

### Connection & Account Info
- `get_company_info` — test QBO connection, get company name/address/details
- `list_connections` — list all connected QBO companies for this user

### Query & Browse
- `query_books` — SQL-like queries against QBO. Params: `{ "query": "SELECT * FROM Invoice WHERE TotalAmt > '1000'" }`
- `get_entity` — fetch a specific entity by type and ID. Params: `{ "entity_type": "Invoice", "entity_id": "123" }`

### Reports (all via get_report)
- `get_report` — run any QBO report. Params: `{ "report": "ProfitAndLoss", "start_date": "2026-01-01", "end_date": "2026-03-31" }`
  - Supported reports: ProfitAndLoss, BalanceSheet, CashFlow, TrialBalance, GeneralLedger, AgedReceivables, AgedReceivableDetail, AgedPayables, AgedPayableDetail, CustomerIncome, VendorExpenses, ProfitAndLossDetail
  - Date macros (use instead of dates): "this month", "last month", "this quarter", "this year", "this fiscal year-to-date" (case-insensitive title case)

### Create & Manage
- `create_invoice` — create an invoice. Params: `{ "customer_id": "123", "line_items": [{ "description": "Consulting", "amount": 1500 }] }`
- `send_invoice` — email an invoice to the customer. Params: `{ "invoice_id": "456" }`
- `record_payment` — record a payment. Params: `{ "customer_id": "123", "amount": 500 }`
- `create_journal_entry` — create a journal entry. Params: `{ "lines": [{ "account_id": "1", "debit": 1000 }, { "account_id": "2", "credit": 1000 }] }`

### AI Analysis
- `cash_flow_forecast` — AI-powered cash flow forecast based on historical data and current balances
- `month_end_checklist` — month-end close readiness check with status for each item
- `find_anomalies` — find unusual transactions (may be slow under rate limiting)

### Known Issues
- `search_customers` — currently broken (QBO QueryParserError on OR queries). Use `query_books` with a Customer query instead.

## Links

- Website: https://kimagic.app
- MCP Endpoint: https://kimagic.app/mcp
- API Health: https://kimagic.app/api/health
- MCP Discovery: https://kimagic.app/.well-known/mcp.json
- OAuth Discovery: https://kimagic.app/.well-known/oauth-protected-resource