# 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](https://github.com/intuit/quickbooks-online-mcp-server),
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.

## 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](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](docs/known-issues.md).

## Installation

```bash
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](https://developer.intuit.com/), 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 :

```env
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`) :

```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.

| Entité | Créer | Lire | Modifier | Supprimer | Chercher |
|--------|:-----:|:----:|:--------:|:---------:|:--------:|
| Customer, Invoice, Estimate, Bill, Vendor, Employee, Item | ✅ | ✅ | ✅ | ✅ | ✅ |
| Journal Entry, Bill Payment, Purchase, Payment | ✅ | ✅ | ✅ | ✅ | ✅ |
| Sales Receipt, Credit Memo, Refund Receipt | ✅ | ✅ | ✅ | ✅ | ✅ |
| Purchase Order, Vendor Credit, Deposit, Transfer | ✅ | ✅ | ✅ | ✅ | ✅ |
| Time Activity, Attachable | ✅ | ✅ | ✅ | ✅ | ✅ |
| Account, Class, Department, Term, Payment Method | ✅ | ✅ | ✅ | | ✅ |
| Tax Code, Tax Rate, Tax Agency | | ✅ | | | ✅ |
| Company Info | | ✅ | ✅ | | |

### Rapports

| Rapport | Outil |
|---------|-------|
| Bilan | `get_balance_sheet` |
| État des résultats | `get_profit_and_loss` |
| Flux de trésorerie | `get_cash_flow` |
| Balance de vérification | `get_trial_balance` |
| Grand livre | `get_general_ledger` |
| Ventes par client | `get_customer_sales` |
| Comptes clients par ancienneté | `get_aged_receivables`, `get_aged_receivables_detail` |
| Solde des clients | `get_customer_balance` |
| Comptes fournisseurs par ancienneté | `get_aged_payables` |
| Dépenses par fournisseur | `get_vendor_expenses` |

## Développement

```bash
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](docs/ARCHITECTURE.md) et [docs/TESTING.md](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](LICENSE). Code d'origine © Intuit, modifications © Antoine Martin.