SideQuest live in 30 minutes.

Five steps. The longest part is the QuickBooks OAuth setup. After that, you process POs by asking Claude Desktop to do it.

Pick your computer. The steps below switch instantly.

Step 0 · Check your email host (30 seconds)

SideQuest reads inbound POs from Gmail natively. Other hosts work via a 10-minute forwarding setup. Type your domain or email address and we'll check the MX records and tell you which path applies.

Step 1 · Install the connector (5 min)

bash install-connector.sh

About 60 seconds in, the installer pauses and asks for your license key. Copy it from your welcome email, paste it in when prompted, press ReturnEnter. The installer saves the key.

When it finishes you see All done and your tier (Free, Starter, etc.). The installer also adds qb-distributor-mcp to your PATH.

Step 2 · Connect QuickBooks via our hosted helper page (3 min)

Fastest path: use the hosted helper at sidequestautomation.com/qb/start. It removes most of the OAuth Playground tangent: paste your Client ID, click one button, sign in to QuickBooks, copy two values back to your terminal. If you'd rather see the underlying Playground flow,If you'd rather see the underlying Playground flow, the steps still work; expand the details below.

2a · Create the Intuit Developer app

1. Open developer.intuit.com/app/developer/myapps. Sign in with your QuickBooks login.
2. Click Create app → QuickBooks Online and Payments. Name it whatever you want (e.g. SideQuest).
3. Open Keys & OAuth → Production (or Development if you're testing). Under Redirect URIs, click Add URI and paste exactly: https://sidequestautomation.com/qb/callback. Save.
4. Copy two values from this page: Client ID and Client Secret. Save them in a temporary text file.

2b · Run the hosted authorization helper

1. Open sidequestautomation.com/qb/start.
2. Paste your Client ID from step 2a into the field. Pick Sandbox or Production.
3. Click Authorize QuickBooks. Intuit opens in a new tab. Sign in, pick the QB company, click Connect.
4. Intuit redirects you to sidequestautomation.com/qb/callback which shows your authorization code and realm ID in two copy-paste boxes.

2c · Write the values into .env

In TerminalPowerShell, paste this block. Replace each YOUR_... with the values from 2b, then press ReturnEnter.

cat > ~/.qb-distributor-mcp/.env <<EOF
QB_CLIENT_ID=YOUR_CLIENT_ID
QB_CLIENT_SECRET=YOUR_CLIENT_SECRET
QB_REALM_ID=YOUR_REALM_ID
QB_REFRESH_TOKEN=YOUR_REFRESH_TOKEN
QB_ENVIRONMENT=sandbox
QB_REDIRECT_URI=http://localhost:8765/callback
GMAIL_PO_LABEL=purchase-orders
EOF

@"
QB_CLIENT_ID=YOUR_CLIENT_ID
QB_CLIENT_SECRET=YOUR_CLIENT_SECRET
QB_REALM_ID=YOUR_REALM_ID
QB_REFRESH_TOKEN=YOUR_REFRESH_TOKEN
QB_ENVIRONMENT=sandbox
QB_REDIRECT_URI=http://localhost:8765/callback
GMAIL_PO_LABEL=purchase-orders
"@ | Set-Content -Path "$HOME\.qb-distributor-mcp\.env"

Step 3 · Connect Gmail via Google Cloud Console (10 min)

3a · Create a Google Cloud project

1. Open console.cloud.google.com signed in as the Gmail account that receives your POs.
2. Accept Google Cloud's Terms of Service if first time.
3. Create project → name it SideQuest Automation. Wait for it to provision.

3b · Enable the Gmail API

1. Open the Gmail API library page. Confirm the project picker at top shows SideQuest Automation.
2. Click Enable.

3c · Configure the OAuth consent screen

1. Open OAuth Overview → click Get started.
2. App name: SideQuest Automation. Support email: your Gmail.
3. Audience: External. (Internal is only for Google Workspace orgs.)
4. Contact email: your Gmail. Agree to the Google API User Data Policy. Create.

3d · Add yourself as a test user

Required. Without this, the OAuth dance fails with access_denied.

1. Click Audience in the left nav.
2. Scroll to Test users → + Add users.
3. Type your Gmail address, press Return, click Save.

3e · Create the Desktop OAuth client

1. Click Clients in the left nav → Create client.
2. Application type: Desktop app. Name: SideQuest Connector. Click Create.

3f · Get the complete client_secret JSON

Google changed the rules. The first time you click Download JSON for a brand-new client, the file Google gives you is missing the client_secret value. You have to add a second secret to the same client and download that one.

1. On the Clients list, click on SideQuest Connector to open the detail page.
2. Scroll to Client secrets. Click + Add secret. A new row appears with a NEW badge; its download icon is active.
3. Click the download icon next to the NEW secret. The file Google saves to Downloads now has "client_secret": "GOCSPX-..." inside.

Move the file into the connector folder:

mv ~/Downloads/client_secret_2_*.apps.googleusercontent.com.json \
  ~/.qb-distributor-mcp/google_client_secret.json

Move-Item "$HOME\Downloads\client_secret_2_*.apps.googleusercontent.com.json" `
  "$HOME\.qb-distributor-mcp\google_client_secret.json"

Verify the file has the secret (Mac):

grep client_secret ~/.qb-distributor-mcp/google_client_secret.json

Select-String -Path "$HOME\.qb-distributor-mcp\google_client_secret.json" -Pattern "client_secret"

You should see "client_secret":"GOCSPX-...". If you see nothing, you grabbed the incomplete first download. Repeat 3f.

3g · Add Gmail paths to .env

printf "\nGOOGLE_CLIENT_SECRETS_PATH=$HOME/.qb-distributor-mcp/google_client_secret.json\nGOOGLE_TOKEN_PATH=$HOME/.qb-distributor-mcp/google_token.json\n" >> ~/.qb-distributor-mcp/.env

Add-Content -Path "$HOME\.qb-distributor-mcp\.env" -Value @"

GOOGLE_CLIENT_SECRETS_PATH=$HOME\.qb-distributor-mcp\google_client_secret.json
GOOGLE_TOKEN_PATH=$HOME\.qb-distributor-mcp\google_token.json
"@

3h · Run the Gmail OAuth dance

~/.qb-distributor-mcp/venv/bin/python -c "
from pathlib import Path
from qb_distributor_mcp.gmail_client import GmailClient
home = Path.home() / '.qb-distributor-mcp'
client = GmailClient(home / 'google_client_secret.json', home / 'google_token.json')
print('Token file:', (home / 'google_token.json').exists())
"

& "$HOME\.qb-distributor-mcp\venv\Scripts\python.exe" -c "from pathlib import Path; from qb_distributor_mcp.gmail_client import GmailClient; home = Path.home() / '.qb-distributor-mcp'; client = GmailClient(home / 'google_client_secret.json', home / 'google_token.json'); print('Token file:', (home / 'google_token.json').exists())"

A browser tab opens. Click your Gmail account. You will see "Google hasn't verified this app." That is normal — your app is in Testing mode because you just created it. Click Advanced (small link, bottom-left), then Go to SideQuest Automation (unsafe), then Continue to grant Gmail read/modify access.

Browser says "The authentication flow has completed." Terminal prints Token file: True.

Step 4 · Wire credentials into Claude Desktop (2 min)

The MCP server Claude Desktop launches does not read ~/.qb-distributor-mcp/.env. It runs from a different working directory, so the env file is invisible to it. The fix is to copy every value from your .env into Claude Desktop's claude_desktop_config.json under the env block.

Paste this one-liner. It reads your .env and writes the config in one shot.

python3 -c "
import json, pathlib
cp = pathlib.Path.home() / 'Library/Application Support/Claude/claude_desktop_config.json'
ep = pathlib.Path.home() / '.qb-distributor-mcp/.env'
env = {k.strip(): v.strip() for line in ep.read_text().splitlines() if line.strip() and not line.startswith('#') and '=' in line for k, v in [line.split('=', 1)]}
cfg = json.loads(cp.read_text()) if cp.exists() else {}
cfg.setdefault('mcpServers', {})
cfg['mcpServers']['qb-distributor'] = {
    'command': str(pathlib.Path.home() / '.qb-distributor-mcp/venv/bin/qb-distributor-mcp'),
    'args': ['serve'],
    'env': env,
}
cp.parent.mkdir(parents=True, exist_ok=True)
cp.write_text(json.dumps(cfg, indent=2))
print('Wrote config with', len(env), 'env vars')
"

py -c "
import json, pathlib, os
cp = pathlib.Path(os.environ['APPDATA']) / 'Claude' / 'claude_desktop_config.json'
ep = pathlib.Path.home() / '.qb-distributor-mcp' / '.env'
env = {k.strip(): v.strip() for line in ep.read_text().splitlines() if line.strip() and not line.startswith('#') and '=' in line for k, v in [line.split('=', 1)]}
cfg = json.loads(cp.read_text()) if cp.exists() else {}
cfg.setdefault('mcpServers', {})
cfg['mcpServers']['qb-distributor'] = {
    'command': str(pathlib.Path.home() / '.qb-distributor-mcp' / 'venv' / 'Scripts' / 'qb-distributor-mcp.exe'),
    'args': ['serve'],
    'env': env,
}
cp.parent.mkdir(parents=True, exist_ok=True)
cp.write_text(json.dumps(cfg, indent=2))
print('Wrote config with', len(env), 'env vars')
"

You should see Wrote config with 9 env vars. If the count is lower, your .env is missing one of the QB or Gmail entries from Steps 2 and 3. Open ~/.qb-distributor-mcp/.env in any text editor and confirm all nine keys are present.

Now fully quit Claude Desktop. Use Claude → Quit Claude or Cmd+Q. Closing the window is not enough.Right-click the Claude icon in the system tray (bottom-right, near the clock) and pick Quit. Closing the window is not enough. Reopen Claude Desktop. You should see qb-distributor in the MCP tool list.

Step 5 · Create the Gmail label and process a test PO (5 min)

In Gmail, scroll the left sidebar, click More → Create new label. Name it exactly the same string you typed in the setup wizard (purchase-orders if you took the default). Save.

Forward a real PO email to yourself (or compose a fake one) and apply the purchase-orders label. Then open Claude Desktop and ask:

List my incoming purchase orders and draft an estimate for each one.

Claude reads the labeled email, parses the PO, matches every line against your QuickBooks catalog, flags pricing variances, and shows you the draft inline in chat. Each draft has a review_url like qbd://drafts/abc123 you can reference in follow-up messages.

To edit, say things like:

• "Change line 2 quantity to 10."
• "Replace the SKU on line 3 with BR-ELB-050-NPT."
• "Apply a 5% discount to the whole draft."

When it looks right, ask Claude to submit:

Submit draft abc123 to QuickBooks.

The Estimate writes to QuickBooks Online. Claude replies with the QB Estimate number and a link to open it in QuickBooks.

Step 6 · (Optional) Build your cross-reference table

This is the single biggest accuracy improvement you can make. SideQuest matches unknown part numbers with fuzzy matching, but customer aliases up front lift Day-1 match accuracy from ~85% to ~99%.

touch ~/.qb-distributor-mcp/cross_reference.csv
open -a TextEdit ~/.qb-distributor-mcp/cross_reference.csv

%USERPROFILE%\.qb-distributor-mcp

Add rows in this format:

customer_id,customer_part,internal_sku,notes
ACME,ACME-EL34,BR-ELB-075-NPT,Acme's catalog code for 3/4" brass elbow
ACME,ACME-EL12,BR-ELB-050-NPT,
,LEGACY-12NPT,BR-ELB-050-NPT,Global alias works for any customer
,COMPETITOR-X1,FS-BOLT-25-100,Picked up from competitor pricing

Leave customer_id blank for global aliases. The matcher prefers a customer-specific row when both exist. Save. Add this line by hand to ~/.qb-distributor-mcp/.env:

CROSS_REFERENCE_CSV=/Users/YOU/.qb-distributor-mcp/cross_reference.csv

CROSS_REFERENCE_CSV=C:\Users\YOU\.qb-distributor-mcp\cross_reference.csv

Rerun the Step 4 one-liner so the new CROSS_REFERENCE_CSV value lands in Claude Desktop's config too. Cmd+Q Claude Desktop, reopen. The next PO uses your new mappings.

You're done

That's the whole loop. From now on:

• Open Claude Desktop.
• Ask "list my incoming purchase orders and draft estimates."
• Review the drafts, edit by chat, ask Claude to submit.
• The Estimate lands in QuickBooks Online.

When you're ready for production, open the OAuth Playground again. Pick SideQuest Connector (Production) from the Select app dropdown, click Get authorization code, pick your real QB company on the Connect screen, then click Get tokens. Open ~/.qb-distributor-mcp/.env and update three values: the new QB_REALM_ID, the new QB_REFRESH_TOKEN, and change QB_ENVIRONMENT=sandbox to QB_ENVIRONMENT=production. Re-run the Step 4 one-liner. Cmd+Q Claude Desktop and reopen.

Verify your setup any time

Run the diagnostic check:

qb-distributor-mcp doctor

It prints your license tier, QB realm ID, Gmail account, and runs a sample call against the demo catalog. Secrets are redacted in the output, so it's safe to paste into a support email.

Troubleshooting common Day-1 issues