CData QuickBooks Online Read-Only MCP Endpoint

This repository details the creation of a specialized, read-only MCP server designed to expose QuickBooks Online ledger information via the CData JDBC Driver for QuickBooks Online.

Attention: This implementation strictly enforces read-only access. For comprehensive CRUD operations and a streamlined deployment experience, please explore the complimentary CData MCP Server for QuickBooks Online (beta).

Core Functionality

The objective is to furnish Large Language Models (LLMs), such as Claude Desktop, with the capability to interrogate live QuickBooks Online data. This is achieved by encapsulating the CData JDBC Driver for QuickBooks Online, which structures QBO entities into an accessible relational SQL framework. The server bridges this structured access layer to the MCP interface, allowing agents to derive insights through conversational queries, bypassing the need for explicit SQL composition.

Implementation Workflow

1. Source Code Acquisition: bash git clone https://github.com/cdatasoftware/quickbooks-online-mcp-server-by-cdata.git cd quickbooks-online-mcp-server-by-cdata

2. Artifact Compilation: bash mvn clean install

   This step generates the executable JAR: CDataMCP-jar-with-dependencies.jar 3. Driver Installation: Obtain and install the necessary CData JDBC Driver for QBO from: https://www.cdata.com/drivers/qbonline/download/jdbc 4. Driver Activation/Licensing: * Locate the driver directory (e.g., C:\Program Files\CData\CData JDBC Driver for QuickBooks Online\ on Windows). * Execute the licensing utility: java -jar cdata.jdbc.quickbooksonline.jar --license * Provide required credentials and use the key "TRIAL" or your licensed key. 5. Data Source Connection Configuration: * Launch the utility for connection string generation: java -jar cdata.jdbc.quickbooksonline.jar * Configure the parameters pointing to your QBO instance (OAuth authentication may require browser interaction). * Save the resulting connection string after a successful test. 6. Server Definition File Creation (.prp): * Generate a properties file (e.g., quickbooks-online.prp) detailing the server's metadata and connection parameters: env Prefix=quickbooksonline ServerName=CDataQuickBooksOnline ServerVersion=1.0 DriverPath=PATH\TO\cdata.jdbc.quickbooksonline.jar DriverClass=cdata.jdbc.quickbooksonline.QuickBooksOnlineDriver JdbcUrl=jdbc:quickbooksonline:InitiateOAuth=GETANDREFRESH; Tables=

Integrating with LLM Clients (e.g., Claude Desktop)

1. Client Configuration Update: Modify or create the client's configuration file (e.g., claude_desktop_config.json) to register the new MCP service. Use the hyphenated class name as the key ({classname_dash}).

   Windows Client Registration Example:

   { "mcpServers": { "{classname_dash}": { "command": "PATH\TO\java.exe", "args": [ "-jar", "PATH\TO\CDataMCP-jar-with-dependencies.jar", "PATH\TO\quickbooks-online.prp" ] }, ... } }

   Linux/Mac Client Registration Example:

   { "mcpServers": { "{classname_dash}": { "command": "/PATH/TO/java", "args": [ "-jar", "/PATH/TO/CDataMCP-jar-with-dependencies.jar", "/PATH/TO/quickbooks-online.prp" ] }, ... } }

   Ensure the configuration file is placed in the client's designated application data directory (e.g., %APPDATA%\Claude\ on Windows). 2. Client Reload/Restart: Relaunch or refresh the AI client to initialize the newly defined data access tools.

Standalone Server Execution

To launch the gateway independently (useful for debugging or clients using standard input/output communication): bash java -jar /PATH/TO/CDataMCP-jar-with-dependencies.jar /PATH/TO/quickbooks-online.prp

Note: This configuration exclusively utilizes stdio for communication, restricting its utility to clients running on the same host machine.

Agent Interaction Paradigm

Upon successful setup, the AI agent gains access to the structured QBO schema via the exposed tools. Agents should be prompted to formulate inquiries naturally. Examples of expected queries: * "Summarize total receivables from the last fiscal quarter." * "Identify any outstanding invoices older than 90 days."

Available Toolset

Tool invocations are prefixed by the server alias defined in the configuration ({servername}). * {servername}_get_tables: Fetches a comma-separated listing of all accessible QBO data entities (tables). * {servername}_get_columns: Retrieves detailed field metadata (columns) for a specified entity. Results are delivered in CSV format. * {servername}_run_query: Executes arbitrary SQL SELECT statements against the QBO data model.

JSON-RPC Invocation Schemas (For Direct Scripting)

Requests adhere to the JSON-RPC 2.0 standard for tool invocation.

Querying Available Tables (Example)

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "quickbooks_online_get_tables", "arguments": {} } }

Inspecting Table Schema (e.g., 'Invoice' table)

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "quickbooks_online_get_columns", "arguments": { "table": "Invoice" } } }

Executing a Data Retrieval Query

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "quickbooks_online_run_query", "arguments": { "sql": "SELECT TotalAmount, CustomerRef FROM [Invoice] WHERE [Status] = 'Open'" } } }

Debugging and Support

1. Visibility Issue: If the server does not appear in the client application, ensure the client process is completely terminated (verify via system task manager).
2. Data Retrieval Failure: Verify the connection string embedded in the .prp file against the output from the Connection String utility.
3. Connectivity Problems: For issues interfacing with QuickBooks Online, consult the CData Support Portal.
4. MCP Server Feedback: For platform-specific issues or suggestions, engage with the CData Community Forum.

Licensing

This software artifact is distributed under the permissive MIT License. Refer to the accompanying LICENSE file for complete usage, modification, and redistribution rights.

Data Source Compatibility Index (Partial List)

This component is part of a broader framework supporting connectivity to numerous enterprise data environments. The QuickBooks Online driver is one implementation within a vast catalog:

Category	Examples
Financial/ERP	SAP, Oracle Financials Cloud, NetSuite, Xero, QuickBooks
CRM/Sales	Salesforce, Dynamics CRM, HubSpot, Sugar CRM
Database/Warehousing	Snowflake, BigQuery, PostgreSQL, SQL Server, Redshift
Collaboration/Productivity	SharePoint, Google Sheets, Jira, Confluence, Slack
Cloud Storage	Amazon S3, Azure Data Lake Storage, Google Cloud Storage

Note: The underlying CData technology supports hundreds of additional connectors, far exceeding the selection shown above.