QuickBooks Online MCP

Mon serveur MCP pour piloter la comptabilité QuickBooks Online de Correctia depuis Claude (app desktop et Claude Code). Je m'en sers pour chercher des transactions, sortir les rapports financiers et saisir des factures, dépenses et écritures sans ouvrir QuickBooks.

C'est un fork du serveur MCP QuickBooks Online d'Intuit, que j'ai adapté à mon usage. Les changements sont listés plus bas.

Ce que ça couvre

• 29 types d'entités : clients, factures, fournisseurs, factures fournisseurs, achats, paiements, écritures de journal, dépôts, virements, taxes, pièces jointes, etc.

• 11 rapports : bilan, état des résultats, flux de trésorerie, balance de vérification, grand livre, comptes clients et fournisseurs par ancienneté, ventes par client, dépenses par fournisseur.

• Authentification OAuth 2.0 avec rafraîchissement automatique du jeton.

Related MCP server: quickbooks-mcp-server

Ce que j'ai changé par rapport à l'original

• Le jeton de rafraîchissement ne meurt plus. Intuit fait tourner le refresh token à chaque rafraîchissement. Le serveur d'origine gardait l'ancien en mémoire, qui finissait par expirer. Maintenant le nouveau jeton est réécrit dans .env à chaque rotation.

• Le .env du dépôt est toujours lu, et il a priorité. L'app Claude lance le serveur avec le dossier / comme répertoire courant et peut lui passer un jeton périmé dans sa config. Le serveur charge donc .env à partir de son propre emplacement et ses valeurs écrasent celles de l'environnement.

• Claude sait se servir des outils. Chaque outil dit ce qu'il fait, quand l'utiliser plutôt qu'un autre, d'où viennent les Id et le SyncToken, les règles qui font refuser l'appel (taxes TPS/TVQ, débits égaux aux crédits) et donne un exemple. Les schémas vides comme purchase: {} sont devenus des objets avec chaque champ documenté. Le tout s'appuie sur la doc officielle d'Intuit, résumée dans docs/qbo-api-reference.md.

• Lecture et suppression sont signalées. Les outils portent les annotations MCP readOnlyHint et destructiveHint, donc Claude peut demander confirmation avant de modifier ou supprimer.

• Outils réparés. Les outils fournisseurs et factures fournisseurs ignoraient leurs paramètres et échouaient toujours. update_bill perdait son SyncToken. delete_vendor désactive maintenant le fournisseur, puisque QuickBooks ne permet pas de le supprimer. Les recherches filtrent vraiment (critères, dates, count), le grand livre fonctionne, et delete_invoice n'annule plus une facture en douce quand la suppression échoue.

• Annuler sans supprimer. Nouveaux outils void_invoice, void_payment et void_sales_receipt.

• TPS/TVQ. Les créations de ventes et d'achats acceptent GlobalTaxCalculation et un code de taxe par ligne, obligatoires pour une entreprise canadienne.

Les problèmes connus qui restent dans les handlers sont listés dans docs/known-issues.md.

Installation

git clone https://github.com/Anto39/qbo-mcp-server.git
cd quickbooks-online-mcp-server
npm install
npm run build

Le build produit dist/index.js, le point d'entrée que Claude lance. Il faut relancer npm run build après chaque modification dans src/.

Configuration

Identifiants QuickBooks

1. Sur le portail développeur d'Intuit, créer une app (ou reprendre l'existante).

2. Récupérer le Client ID et le Client Secret.

3. Ajouter http://localhost:8000/callback dans les Redirect URIs de l'app.

Fichier .env

À la racine du dépôt :

QUICKBOOKS_CLIENT_ID=...
QUICKBOOKS_CLIENT_SECRET=...
QUICKBOOKS_REFRESH_TOKEN=...
QUICKBOOKS_REALM_ID=...
QUICKBOOKS_REDIRECT_URI=http://localhost:8000/callback
QUICKBOOKS_ENVIRONMENT=production

Mettre QUICKBOOKS_ENVIRONMENT=sandbox pour tester sur une entreprise de démo.

Sans refresh token, npm run auth lance le flux OAuth : un petit serveur local s'ouvre, le navigateur demande l'autorisation, puis les jetons sont enregistrés dans .env.

Ne jamais committer .env avec de vrais identifiants.

Brancher sur Claude

App desktop (~/Library/Application Support/Claude/claude_desktop_config.json) ou Claude Code (claude mcp add ou ~/.claude.json) :

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/chemin/vers/quickbooks-online-mcp-server/dist/index.js"]
    }
  }
}

Les identifiants peuvent rester dans .env : pas besoin de les recopier dans la config de Claude.

Outils

Chaque entité a ses outils create_*, get_*, update_*, delete_* et search_*, sauf exceptions ci-dessous.

Rapports

Développement

npm run build   # compile src/ vers dist/
npm run watch   # recompile à chaque modification
npm test        # tests Jest

src/
├── clients/    # client API QuickBooks (OAuth, rafraîchissement du jeton)
├── handlers/   # un fichier par opération
├── tools/      # définitions des outils MCP
├── helpers/
├── types/
└── index.ts    # point d'entrée

Plus de détails : docs/ARCHITECTURE.md et docs/TESTING.md.

Si ça ne se connecte pas

1. Vérifier les variables dans .env.

2. Un jeton expiré ou révoqué se règle avec npm run auth.

3. Vérifier que la Redirect URI de l'app Intuit correspond à QUICKBOOKS_REDIRECT_URI.

4. Après une modification du code, refaire npm run build et redémarrer Claude.

Licence

Apache 2.0, voir LICENSE. Code d'origine © Intuit, modifications © Antoine Martin.