Connect CrewAI to QuickBooks Online: Python MCP Setup (2026)

The current CrewAI setup is short: configure a remote MCP server on an agent with the mcps field, authenticate with a bearer key, and start with a read-only task. You do not need to build an Intuit app when a hosted MCP provider already owns the QuickBooks OAuth connection.

This guide uses DeepLedger's hosted endpoint. The same CrewAI pattern works with another remote MCP server if its URL, authentication, tool names, and authorization model are compatible.

What You Need

• Python 3.10 through 3.13. CrewAI's current installation guide requires Python 3.10 or newer and below 3.14.
• A recent CrewAI project and the mcp dependency.
• A DeepLedger account with the intended QuickBooks Online company connected.
• Permission to create a user API key under Settings > API Access.
• A model-provider credential configured according to CrewAI's LLM documentation.

The QuickBooks connection and the CrewAI connection are separate. DeepLedger connects to QuickBooks through Intuit OAuth. CrewAI connects to DeepLedger through MCP with a DeepLedger key. The crew never needs your QuickBooks password.

Step 1: Install CrewAI's MCP Dependency

Inside an existing CrewAI project, add the MCP package:

uv add mcp

If you are starting from scratch, follow CrewAI's current project setup first, then add mcp. The older MCPServerAdapter route requires crewai-tools[mcp]; the code below uses CrewAI's recommended mcps field instead.

Step 2: Create a DeepLedger API Key

In DeepLedger, open Settings > API Access, choose Create API Key, set an expiration, and copy the key when it is shown. The full value is not available again.

Put it in your environment or secret manager, not in source code:

export DEEPLEDGER_API_KEY="dl_live_..."

A user key acts as the person who created it. It can reach the companies that person can access, following the person's active company. It is not the same as DeepLedger's organization-fixed automation credential.

Step 3: Make the First Connection Read-Only

CrewAI's MCPServerHTTP is the structured configuration for a remote Streamable HTTP server. This example uses a static tool filter so the agent can identify the company and run reports, but cannot see recording tools.

import os

from crewai import Agent, Crew, Task
from crewai.mcp import MCPServerHTTP
from crewai.mcp.filters import create_static_tool_filter

deepledger = MCPServerHTTP(
    url="https://mcp.deepledger.ai/mcp",
    headers={
        "Authorization": f"Bearer {os.environ['DEEPLEDGER_API_KEY']}"
    },
    streamable=True,
    tool_filter=create_static_tool_filter(
        allowed_tool_names=["qbCompanyProfile", "qbReports"]
    ),
)

analyst = Agent(
    role="QuickBooks report analyst",
    goal="Return a dated report from the correct company without changing the books.",
    backstory=(
        "You verify the company, currency, report dates, and accounting basis "
        "before explaining any totals. You do not infer missing rows."
    ),
    mcps=[deepledger],
    verbose=True,
)

check_report = Task(
    description=(
        "First call qbCompanyProfile with operation profile. Then run a "
        "ProfitAndLoss report for 2026-08-01 through 2026-08-31 on the "
        "accrual basis. State the company, home currency, exact dates, basis, "
        "and whether the report says more rows remain. Do not call a write tool."
    ),
    expected_output=(
        "A concise report check naming the company, currency, dates, basis, "
        "completeness status, income, expenses, and net income."
    ),
    agent=analyst,
)

result = Crew(agents=[analyst], tasks=[check_report]).kickoff()
print(result)

Replace the dates with a period you can compare directly in QuickBooks. Do not treat a plausible total as proof. In QuickBooks Online, run the same report with the same start date, end date, and accounting basis, then compare the company name and totals.

The sample is syntactically complete, but it cannot prove your credentials, model configuration, network, or company data. Those are verified only when you run it in your environment.

Step 4: Confirm the Company Before Every Run

DeepLedger's person-level API key is not fixed to one company. The active company is shared across that person's connected AI clients.

For a single-company report, the profile call in the sample is the check. For a multi-company process:

1. Call qbCompanyProfile with operation: "list".
2. Select the exact organizationId from that result.
3. Call qbCompanyProfile with operation: "switch" and that ID.
4. Read the company echoed by the switch result.
5. Run the report and check the company echoed in the report result too.

Do not switch by a guessed company name when two clients are similar. A switch also changes the active company for the same person's other connected clients, so a long-running job should confirm the company on each unit of work. See the multiple-company connection guide for the full behavior.

Step 5: Decide Which Tools the Agent Should See

The tool filter in the example is deliberately small:

allowed_tool_names=["qbCompanyProfile", "qbReports"]

That is enough for a useful reporting job. Add tools only when the task needs them. For example, transaction research may also need qbFetchTransactions and qbMasterData.

Filtering tools in CrewAI reduces accidental calls and keeps the model's tool list focused. It does not narrow the capability of the bearer key itself. Anyone who obtains that user key can present it directly to the MCP server, subject to the server's authorization rules. Use an expiring key where practical, store it in a real secret store, and revoke it under API Access if the job or host is retired.

Troubleshooting the Connection

ModuleNotFoundError: No module named 'mcp'

Add the dependency to the CrewAI project with uv add mcp, then reinstall or sync the project environment. CrewAI's current mcps integration and the older adapter are different APIs, so follow one setup consistently.

ImportError: cannot import name 'MCPServerAdapter'

You are following an older adapter example without its optional package. For the current approach, import MCPServerHTTP from crewai.mcp and pass it through the agent's mcps field. If you intentionally need manual connection lifecycle control, CrewAI documents the adapter separately and requires crewai-tools[mcp].

401 Unauthorized

Check all three parts:

• The header value starts with Bearer .
• The key was copied in full and has not expired.
• The key has not been revoked in DeepLedger's API Access settings.

Do not print the key while debugging. Log the response status and a safe key prefix only.

The tools load, but the report names the wrong company

Call qbCompanyProfile with operation: "list", switch with the exact organization ID, and rerun the profile check. The active company is shared for that user, so another connected client may have changed it. DeepLedger adds company context to object-shaped tool results. Confirm the company in the profile and report responses, and treat a mismatch as a stop condition.

A required tool is missing

Check allowed_tool_names. A static filter hides every tool not on its allowlist. Add only the exact tool name the task needs. If even qbCompanyProfile is unavailable, remove the filter temporarily in a safe local test to distinguish a filter mistake from connection failure.

The connection times out

Confirm the endpoint matches the DeepLedger MCP URL in step 3, then check outbound HTTPS access from the runtime. With MCPServerHTTP, Streamable HTTP is represented by streamable=True, which is also the default. The hyphenated streamable-http string belongs to the older adapter configuration, not this structured API.

Installation fails on Python 3.14

CrewAI's current documentation requires Python below 3.14. Use Python 3.10 through 3.13 for this setup.

Scheduling Without Expanding the Risk

After the read-only script works interactively, a job runner can execute it on a schedule. Keep the model-provider key and DeepLedger key in the runner's secret store, use an explicit date period, retain the report output, and alert when the run fails or names the wrong company.

Do not convert the sample into an unattended recording job merely by adding write-tool names. A personal dl_live_ key is not a read-only credential, CrewAI's filter is a client-side control, and a generated report is not human approval for a ledger change. Automated writes need a separately designed workflow with bounded operations, duplicate and open-document checks, durable review state, failure recovery, and testing against an Intuit sandbox before production books.

If the work is interactive rather than scheduled, a chat client may be simpler. Use the Claude setup guide or ChatGPT setup guide. If you are comparing local, self-hosted, and hosted servers, start with the QuickBooks MCP server guide.

Frequently Asked Questions

How do I connect CrewAI to QuickBooks Online?

Use CrewAI's mcps field with an MCPServerHTTP configuration. Point it at a hosted QuickBooks MCP endpoint, send the server's credential in the Authorization header, and give the configuration to the agent that needs the tools. The example in this guide exposes only company-profile and report tools for the first run.

Do I need an Intuit developer account?

Not when you use a hosted provider such as DeepLedger. You connect the QuickBooks Online company to that provider once through Intuit OAuth, then CrewAI connects to the provider's MCP endpoint. A direct QuickBooks API integration is different and does require your own Intuit app and OAuth implementation.

Which CrewAI MCP transport should I use?

Use MCPServerHTTP for a remote Streamable HTTP endpoint. Its streamable option defaults to true. The older MCPServerAdapter API uses a transport string such as streamable-http, but CrewAI's current documentation recommends the mcps field for ordinary agent integrations.

Which QuickBooks company will the crew use?

A DeepLedger user key acts as its creator and follows that person's active company. Call qbCompanyProfile with operation: "list", then switch by organization ID when needed. Confirm the company echoed by the profile and report tools before relying on a report or authorizing a write because switching is shared across that person's connected clients.

Is this sample allowed to write to QuickBooks?

The CrewAI agent in this guide sees only qbCompanyProfile and qbReports, so its sample task is read-only. That tool filter reduces what this agent can call, but it does not turn the underlying DeepLedger user key into a read-only credential. Keep the key secret and do not expose recording tools until you have designed and tested a separate review process.

Can I schedule the CrewAI report?

Yes. Run the same read-only script from your job runner after it succeeds interactively. Store the DeepLedger and model-provider credentials in the runner's secret store, use an expiring key when practical, and alert on failures. Scheduling writes needs additional controls and is not covered by this example.

Sources

• CrewAI: MCP servers as tools
• CrewAI: installation and supported Python versions
• Model Context Protocol: Streamable HTTP

Use a demo or sandbox company for the first run. Compare the result in QuickBooks before you widen the tool list.