CData Read-Only Interface for QuickBooks Online via MCP

This repository hosts the source code for a specific implementation of a CData Model Context Protocol (MCP) server. This server is strictly configured for read-only operations against your live QuickBooks Online environment, leveraging the robust CData JDBC Driver for QuickBooks Online.

:warning: Important Limitation: This specific build is designed exclusively for data retrieval. For comprehensive data manipulation capabilities (CRUD operations, actions), please utilize the fully featured, free CData MCP Server for QuickBooks Online (beta) distribution, available for download here: CData MCP Server Link.

Objective

The primary goal of this component is to bridge Large Language Models (LLMs), such as Claude Desktop, directly to live QuickBooks Online figures. By wrapping the underlying CData JDBC Driver—which abstracts the financial data into relational SQL paradigms—this server exposes the data model via the standardized MCP interface. This allows AI agents to execute complex data queries using conversational prompts instead of requiring explicit SQL scripting.

Deployment Procedure

Follow these steps to compile and configure the server:

1. Source Retrieval: Obtain the project source code: bash git clone https://github.com/cdatasoftware/quickbooks-online-mcp-server-by-cdata.git cd quickbooks-online-mcp-server-by-cdata

2. Artifact Generation: Compile the project using Maven to produce the necessary JAR file: bash mvn clean install

   The executable artifact, CDataMCP-jar-with-dependencies.jar, will be generated. 3. Driver Acquisition: Secure the necessary CData JDBC Driver for QuickBooks Online installation package: Download Link 4. Driver Licensing: Activate the driver: * Locate the installed driver directory (e.g., C:\Program Files\CData\CData JDBC Driver for QuickBooks Online\ on Windows). * Execute the licensing utility: bash java -jar cdata.jdbc.quickbooksonline.jar --license

   • Input your credentials and use "TRIAL" or your procured license code.
   • Data Source Configuration: Establish the connection parameters:
   • Execute the driver to launch the connection utility: java -jar cdata.jdbc.quickbooksonline.jar
   • Define and validate your QuickBooks Online connection string (OAuth authentication may require browser interaction).
   • Once testing is successful, capture the resulting JDBC connection string.
   • Configuration File Creation (.prp): Generate a properties file (e.g., quickbooks-online.prp) detailing the server mapping:
   • Prefix: Identifier prefix for exposed resources.
   • ServerName: A unique designation for this server instance.
   • ServerVersion: Version identifier.
   • DriverPath: Absolute path to the downloaded JDBC driver JAR.
   • DriverClass: Fully qualified name of the JDBC driver class (e.g., cdata.jdbc.quickbooksonline.QuickBooksOnlineDriver).
   • JdbcUrl: The connection string copied in the previous step.
   • Tables: Specify table names if you wish to restrict access; leave empty to expose all accessible schemas. 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=

Integration with Client Applications (e.g., Claude Desktop)

To enable the AI client to invoke this server, integrate it into the client's configuration file (e.g., claude_desktop_config.json):

1. Configuration File Update: Append the server definition to the mcpServers object within the client's configuration.

   Windows Invocation:

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

   Linux/Mac Invocation:

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

2. Configuration Deployment (if necessary): Ensure the modified configuration file resides in the client's expected directory for recognition.

   Windows Path: bash cp /PATH/TO/claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json

   Linux/Mac Path: bash cp /PATH/TO/claude_desktop_config.json /Users/{user}/Library/Application\ Support/Claude/claude_desktop_config.json

3. Client Activation: Restart or refresh the calling client application to load the newly defined MCP endpoint.

Direct Server Execution

The server can be initiated independently for testing purposes: bash java -jar /PATH/TO/CDataMCP-jar-with-dependencies.jar /PATH/TO/Salesforce.prp

Note: Communication relies on standard input/output (stdio), meaning the executing client must reside on the same host as the server process.

Operational Methodology

Upon successful integration, the AI client will automatically discover the available functions exposed by this server. Instead of manual tool invocation, users should pose direct questions concerning their QuickBooks Online data. For example:

• "Analyze the total outstanding receivables grouped by customer segment."
• "List all expenses categorized under 'Travel' for the preceding fiscal quarter."
• "What is the balance summary for my primary operating bank account as of yesterday?"

Available Functions & Signatures

In the subsequent descriptions, {servername} is the unique name assigned to the server in the configuration (e.g., {classname_dash}). * {servername}_get_tables: Fetches a delimited list of all accessible data entities. For schema discovery, chain this with the column retrieval tool. * {servername}_get_columns: Retrieves the attribute list (schema) for a specified data entity, returned in CSV format (including headers). * {servername}_run_query: Executes arbitrary SQL SELECT statements against the exposed QuickBooks Online data model.

JSON-RPC Call Samples (For Scripted Interaction)

If bypassing an AI frontend and scripting direct interaction based on the JSON-RPC 2.0 specification, utilize these payload structures:

Fetching Table Schemas

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

Inspecting Entity Columns (Example: 'Account')

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

Executing a Data Retrieval Command

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "quickbooks_online_run_query", "arguments": { "sql": "SELECT Name, Balance FROM [Account] WHERE Type = 'Bank'" } } }

Common Issue Resolution

1. Server Not Visible in Client: Ensure the host client application (e.g., Claude Desktop) has been completely shut down (verify no background processes remain in Task Manager/Activity Monitor) before restarting.
2. Data Retrieval Failures: Double-check the .prp file entries, especially verifying that the JdbcUrl precisely matches the string validated using the CData Connection String utility.
3. Connectivity Problems: For issues authenticating against QuickBooks Online, engage the CData Technical Support Channel.
4. Server Functionality Feedback: For suggestions or issues related to the MCP server wrapper itself, please contribute to the CData Developer Forum.

Licensing

This server implementation is distributed under the permissive MIT License. Full terms are documented in the accompanying LICENSE file.

Driver Compatibility Matrix

This server is compatible with the CData JDBC Driver for QuickBooks Online and can interact with a vast ecosystem of other data sources supported by CData technology. A selection of supported targets includes:

Category	Examples
ERP/Accounting	SAP, Oracle Financials Cloud, NetSuite, Xero, QuickBooks (non-Online)
CRM	Salesforce, Dynamics CRM, HubSpot, Zoho CRM
Databases	PostgreSQL, MySQL, SQL Server, Oracle, BigQuery, Snowflake
Cloud Storage	Amazon S3, Azure Data Lake Storage, Google Cloud Storage, SharePoint
General APIs	REST, OData, GraphQL, MailChimp, Jira, Zendesk

A complete list of over 300 supported connectors is available via the CData documentation.