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

Note

Make sure syntra-odbc.exe is on your system PATH, or use the full path to the executable (for example C:\\Program Files\\Syntra ODBC\\syntra-odbc.exe).

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/"
    }
  }
}

Remote / multi-user setups

The endpoint binds to 127.0.0.1 by default. To allow connections from another machine on your LAN, set host = "0.0.0.0" in config.toml and replace 127.0.0.1 in the client URL with the host’s IP address. Use TLS or an SSH tunnel if you do this on an untrusted network.

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. Supports SELECT, INSERT, UPDATE, DELETE, and Syntra’s special commands.

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.

Note

Header and line fields are emitted in the order defined by the qbXML <xsd:sequence> schema, regardless of the order you pass them in JSON.

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