MCP Server Setup

Syntra ODBC includes a built-in MCP (Model Context Protocol) server that lets AI assistants query, write, and run QuickBooks Desktop’s native reports through natural language or direct tool calls.

Supported AI Tools

Any MCP-compatible tool works, including:

Claude Code (CLI)
Claude Desktop
Cursor
Windsurf
VS Code (with MCP extensions)
JetBrains IDEs
Gemini CLI

Connection Modes

stdio mode (recommended)

The AI tool spawns syntra-odbc.exe --mcp-stdio as a subprocess. Zero configuration, instant connection.

Add this to your MCP settings:

{
  "mcpServers": {
    "quickbooks": {
      "command": "syntra-odbc.exe",
      "args": ["--mcp-stdio"]
    }
  }
}

Where to put this:

Claude Code: ~/.claude/settings.json or project .claude/settings.json
Cursor: Settings → MCP Servers
Windsurf: MCP configuration file

HTTP / SSE mode

When the Syntra ODBC GUI is running, an MCP endpoint is exposed on port 5434 by default. The endpoint speaks the MCP Streamable HTTP transport, which is SSE-compatible.

Step 1. Enable the network MCP server in config.toml:

[mcp]
enabled = true
host = "127.0.0.1"
port = 5434

Or toggle it in the GUI: Settings → MCP Server → Enable.

Step 2. Point your AI tool’s MCP settings at the URL:

{
  "mcpServers": {
    "quickbooks": {
      "type": "http",
      "url": "http://127.0.0.1:5434/"
    }
  }
}

Available Tools

The MCP server exposes tools grouped by purpose.

Discovery

Tool	Description
`list_tables`	Discover all QuickBooks entity tables, including line tables and singletons
`describe_table`	Get column definitions, types, writability, and required-for-insert flags
`accounting_guide`	Built-in QuickBooks knowledge base covering AR, AP, chart of accounts, sales tax, inventory, job costing, payroll, reconciliation, and more
`list_native_reports`	List every native QuickBooks report currently exposed through Syntra’s shared report engine

Querying

Tool	Description
`query`	Run SQL directly against Syntra’s PostgreSQL-compatible interface

Curated accounting reports

These tools return accountant-friendly JSON shaped for common workflows, while still using the native QuickBooks report engine where applicable.

Tool	Description
`customer_balance`	Open balances by customer, optionally filtered to one customer name
`net_sales_by_period`	Net sales matching QuickBooks sales summary logic over a date range
`profit_and_loss`	Native QuickBooks Profit & Loss for the requested date range, returned as structured income / COGS / expense sections
`balance_sheet`	Native QuickBooks Balance Sheet for the requested as-of date, grouped into assets, liabilities, and equity
`trial_balance`	Native QuickBooks Trial Balance with debit and credit columns for the requested as-of date
`ar_aging_report`	AR aging from open invoices and statement charges
`ap_aging_report`	AP aging from open bills

Native QuickBooks reports

These tools expose QuickBooks Desktop’s report engine directly.

Tool	Description
`qb_report`	Run any supported native report and return a human-oriented wide JSON shape with one row object per report line
`qb_report_raw`	Run any supported native report and return the raw normalized columns-and-cells JSON shape
`general_ledger_report`	Native General Ledger report for a date range
`journal_report`	Native Journal report for a date range
`audit_trail_report`	Native Audit Trail report for a date range
`inventory_valuation_summary`	Native Inventory Valuation Summary for an as-of date
`inventory_valuation_detail`	Native Inventory Valuation Detail for a date range

Writing

Tool	Description
`insert_record`	Create new records. Supports nested `_lines` arrays for invoices, sales receipts, credit memos, bills, inventory adjustments, journal entries, estimates, sales orders, purchase orders, and build assemblies in one call
`update_record`	Modify existing records by SQL `WHERE` clause, with automatic edit-sequence handling
`delete_record`	Delete records by ID (`ListID` or `TxnID`)
`void_transaction`	Void invoices, checks, bill payments, sales receipts, and credit memos
`preview_journal_entry`	Validate accounts and confirm debits = credits before any write

Status

Tool	Description
`cache_status`	Check per-entity sync freshness and last sync timestamps
`connection_status`	View QuickBooks connection state, company file, edition, and QBXML version

Memory layer

Persistent, scoped memory that survives across MCP sessions. Use these to give your AI assistant durable context about your vendors, customers, and naming conventions.

Tool	Description
`get_customer_context`	Load confirmed line aliases, profile, and recent decisions for a customer in one call. Use at the start of any AR workflow
`get_vendor_context`	Load confirmed line aliases, profile, and recent decisions for a vendor in one call. Use at the start of any AP workflow (bill booking, statement reconciliation)
`learn_customer_line_alias`	Remember that a raw customer PO line text maps to an internal inventory item
`learn_vendor_line_alias`	Remember that a raw vendor invoice line text maps to an internal inventory item
`recall_facts`	Search scoped key-value facts using SQL `LIKE` patterns
`record_fact`	Persist a scoped key-value fact across sessions

Native report parameters and customization

qb_report and the report-specific wrappers accept the same date arguments you would expect from QuickBooks:

range reports: start_date + end_date
as-of reports: as_of_date
no-date reports: no dates at all

The generic qb_report tool accepts:

report_type
start_date
end_date
as_of_date
options_json

`options_json`

options_json is a string containing JSON, not a nested object. Use it for native QuickBooks modifiers and filters such as:

report_basis
report_date_macro
report_detail_level_filter
report_posting_status_filter
account_filter
entity_filter
item_filter
class_filter
txn_type_filter_list
summarize_columns_by
include_subcolumns
return_rows
return_columns
summarize_rows_by
include_column_list
include_accounts
report_open_balance_as_of

Example qb_report parameters:

{
  "report_type": "InventoryValuationSummary",
  "as_of_date": "2026-03-31",
  "options_json": "{\"report_basis\":\"Accrual\"}"
}

Example with an account filter:

{
  "report_type": "MissingChecks",
  "start_date": "2026-01-01",
  "end_date": "2026-03-31",
  "options_json": "{\"account_filter\":{\"full_names\":[\"Bank of America\"]}}"
}

Important report caveats

MissingChecks requires an explicit account selection by full_names, list_ids, full_name_with_children, or list_id_with_children. type_filter alone is not enough.
PhysicalInventoryWorksheet must be called with no dates.
Some reports depend on QuickBooks features or setup. When Syntra knows a report would otherwise trigger a QuickBooks modal dialog, it blocks the request and returns an explicit error instead of freezing the session.
qb_report returns the human-oriented wide JSON shape. Use qb_report_raw if you need the underlying normalized report columns and cells.

For the full SQL-side procedure reference and more examples, see Native Reports.

Nested-line inserts

Line-bearing transactions (invoices, bills, inventory adjustments, journal entries, and more) must be inserted as a single qbXML Add request containing the header and every line item. The MCP server exposes this through a _lines array on the insert_record payload.

Inventory adjustment (set CUSTOM ITEM 3 to 500 pcs from 615)

{
  "table": "inventory_adjustments",
  "data": {
    "account_ref_list_id": "8000002F-1754012118",
    "txn_date": "2026-04-07",
    "memo": "Adjust CUSTOM ITEM 3 to 500 pcs",
    "_lines": [
      {
        "item_ref_list_id": "80000042-1719080577",
        "quantity_difference": -115
      }
    ]
  }
}

Invoice with two lines

{
  "table": "invoices",
  "data": {
    "customer_ref_full_name": "Acme:Job 1",
    "txn_date": "2026-04-07",
    "_lines": [
      { "item_ref_full_name": "Hours",  "quantity": 4, "rate": 150.00 },
      { "item_ref_full_name": "Travel", "quantity": 1, "amount": 75.00 }
    ]
  }
}

Journal entry (debit/credit)

{
  "table": "journal_entries",
  "data": {
    "txn_date": "2026-04-07",
    "_lines": [
      { "journal_line_type": "Debit",  "account_ref_full_name": "Office Supplies", "amount": 100.00, "memo": "April supplies" },
      { "journal_line_type": "Credit", "account_ref_full_name": "Checking",        "amount": 100.00, "memo": "April supplies" }
    ]
  }
}

Multiple parents in one call

{
  "table": "invoices",
  "data": [
    { "customer_ref_full_name": "Customer A", "_lines": [ /* ... */ ] },
    { "customer_ref_full_name": "Customer B", "_lines": [ /* ... */ ] }
  ]
}

The response returns the new TxnID or ListID values in the returning array so you can immediately query, void, or delete the record you just created.

Available Resources

The MCP server also exposes resources organized into schema/status, accounting overviews, and per-topic accounting guides.

Schema and status

Resource	URI
Table catalog	`qb://schema/tables`
Per-table schema	`qb://schema/{table}`
Cache health	`qb://status/cache`
Connection info	`qb://status/connection`

Accounting overviews

Resource	URI
Accounting overview	`qb://accounting/overview`
Accounting topic list	`qb://accounting/topics`
Accounting query patterns	`qb://accounting/query-patterns`

Per-topic accounting guides

One resource per accounting_guide topic.

qb://accounting/topic/{topic} where {topic} is one of ar, ap, chart_of_accounts, sales, sales_tax, pricing, multi_currency, inventory, job_costing, payroll, journal_entries, entity_relationships, gotchas, financial_statements, transaction_universe, amount_fields, report_parity, nested_inserts, or reconciliation.

Example interactions

Accounting:

“We paid $500 for office supplies with the company credit card, book it”

The AI can look up your chart of accounts, preview the journal entry, and write the final transaction after confirmation.

Native reporting:

“Show me the inventory valuation summary as of March 31, 2026 on accrual basis”

The AI can call inventory_valuation_summary directly or use qb_report with report_type = InventoryValuationSummary and options_json = {"report_basis":"Accrual"}.

Data lookup:

“What’s the email for customer Acme Corp?”

The AI can run a SQL query such as SELECT email, phone FROM customers WHERE full_name LIKE '%Acme%'.

Technical details

Built on the official MCP SDK from the Model Context Protocol maintainers
Shares the same session context, cache, and QuickBooks COM session as the SQL server
Exposes both curated accounting tools and QuickBooks native reports through the same application
Uses the same write pipeline for insert_record, update_record, delete_record, and void_transaction as the SQL server