qontoctl

![QontoCtl: The Complete CLI & MCP for Qonto](https://raw.githubusercontent.com/qontoctl/.github/main/profile/assets/social-preview.png)

[![CI](https://github.com/alexey-pelykh/qontoctl/actions/workflows/ci.yml/badge.svg)](https://github.com/alexey-pelykh/qontoctl/actions/workflows/ci.yml)
[![Codecov](https://img.shields.io/codecov/c/github/alexey-pelykh/qontoctl?logo=codecov)](https://codecov.io/gh/alexey-pelykh/qontoctl)
[![npm version](https://img.shields.io/npm/v/qontoctl?logo=npm)](https://www.npmjs.com/package/qontoctl)
[![npm downloads](https://img.shields.io/npm/dm/qontoctl?logo=npm)](https://www.npmjs.com/package/qontoctl)
[![GitHub Repo stars](https://img.shields.io/github/stars/alexey-pelykh/qontoctl?style=flat&logo=github)](https://github.com/alexey-pelykh/qontoctl)
[![License](https://img.shields.io/github/license/alexey-pelykh/qontoctl)](LICENSE)

CLI and MCP server for the [Qonto](https://qonto.com) banking API.

This project is brought to you by [Alexey Pelykh](https://github.com/alexey-pelykh).

## What It Does

QontoCtl lets AI assistants (Claude, etc.) interact with Qonto through the [Model Context Protocol](https://modelcontextprotocol.io). It can:

- **Organizations** — retrieve organization details and settings
- **Accounts** — list, create, update, close bank accounts; download IBAN certificates
- **Transactions** — list, search, filter bank transactions; manage transaction attachments
- **Bank Statements** — list, view, and download bank statements
- **Labels** — manage transaction labels and categories
- **Memberships** — view team members, show current membership, invite new members
- **SEPA Beneficiaries** — list, add, update, trust/untrust SEPA beneficiaries
- **SEPA Transfers** — list, create, cancel transfers; download proofs; verify payees
- **Internal Transfers** — create transfers between accounts in the same organization
- **Bulk Transfers** — list and view bulk transfer batches
- **Recurring Transfers** — list and view recurring transfers
- **Terminals (POS)** — list Qonto Terminals and initiate terminal payments
- **Products** — list catalogue products
- **Clients** — list, create, update, delete clients
- **Client Invoices** — full lifecycle: create, update, finalize, send, mark paid, cancel, upload files
- **Quotes** — create, update, delete, send quotes
- **Credit Notes** — list and view credit notes
- **Supplier Invoices** — list, view, and bulk-create supplier invoices
- **Requests** — list organization requests
- **Attachments** — upload and view attachments
- **E-Invoicing** — retrieve e-invoicing settings

## Prerequisites

- **Node.js** >= 24
- A **Qonto** business account with API access

## Installation

```sh
npm install -g qontoctl
```

Or run directly with npx:

```sh
npx qontoctl --help
```

Or install via [Homebrew](https://brew.sh):

```sh
brew install qontoctl/tap/qontoctl
```

## Quick Start

```sh
# 1. Install
npm install -g qontoctl

# 2. Create a profile with your Qonto API credentials
qontoctl profile add mycompany

# 3. Test the connection
qontoctl profile test --profile mycompany

# 4. List your accounts
qontoctl account list --profile mycompany
```

## MCP Integration

QontoCtl implements the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), letting AI assistants interact with your Qonto account through natural language.

### MCP Client Configuration

<details>
<summary><b>Claude Desktop</b></summary>

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}
```

</details>

<details>
<summary><b>Claude Code</b></summary>

```sh
claude mcp add qontoctl -- npx qontoctl mcp
```

</details>

<details>
<summary><b>Cursor</b></summary>

Add to `.cursor/mcp.json` in your project root:

```json
{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}
```

</details>

#### Pointing MCP at a non-default config file

The MCP server has no CLI flags. To load credentials from a config file other than `~/.qontoctl.yaml`, set `QONTOCTL_CONFIG_FILE` in the host's `env` block:

```jsonc
{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"],
            "env": {
                "QONTOCTL_CONFIG_FILE": "/abs/path/to/qontoctl.yaml",
            },
        },
    },
}
```

The path is captured at server startup. See [`docs/configuration.md`](docs/configuration.md) for the full resolution chain.

### Available MCP Tools

| Tool                            | Description                                                           |
| ------------------------------- | --------------------------------------------------------------------- |
| **Organization**                |                                                                       |
| `org_show`                      | Show organization details including name, slug, and bank accounts     |
| **Accounts**                    |                                                                       |
| `account_list`                  | List all bank accounts for the organization                           |
| `account_show`                  | Show details of a specific bank account                               |
| `account_iban_certificate`      | Download IBAN certificate PDF for a bank account                      |
| `account_create`                | Create a new bank account                                             |
| `account_update`                | Update an existing bank account                                       |
| `account_close`                 | Close a bank account                                                  |
| **Transactions**                |                                                                       |
| `transaction_list`              | List transactions for a bank account with optional filters            |
| `transaction_show`              | Show details of a specific transaction                                |
| `transaction_attachment_list`   | List attachments for a transaction                                    |
| `transaction_attachment_add`    | Attach a file to a transaction                                        |
| `transaction_attachment_remove` | Remove attachment(s) from a transaction                               |
| **Statements**                  |                                                                       |
| `statement_list`                | List bank statements with optional filters                            |
| `statement_show`                | Show details of a specific bank statement                             |
| **Labels**                      |                                                                       |
| `label_list`                    | List all labels in the organization                                   |
| `label_show`                    | Show details of a specific label                                      |
| **Memberships**                 |                                                                       |
| `membership_list`               | List all memberships in the organization                              |
| `membership_show`               | Show the current authenticated user's membership                      |
| `membership_invite`             | Invite a new member to the organization                               |
| **SEPA Beneficiaries**          |                                                                       |
| `beneficiary_list`              | List SEPA beneficiaries in the organization                           |
| `beneficiary_show`              | Show details of a specific SEPA beneficiary                           |
| `beneficiary_add`               | Create a new SEPA beneficiary                                         |
| `beneficiary_update`            | Update an existing SEPA beneficiary                                   |
| `beneficiary_trust`             | Trust one or more SEPA beneficiaries                                  |
| `beneficiary_untrust`           | Untrust one or more SEPA beneficiaries                                |
| **SEPA Transfers**              |                                                                       |
| `transfer_list`                 | List SEPA transfers with optional filters                             |
| `transfer_show`                 | Show details of a specific SEPA transfer                              |
| `transfer_create`               | Create a SEPA transfer                                                |
| `transfer_cancel`               | Cancel a pending SEPA transfer                                        |
| `transfer_proof`                | Download SEPA transfer proof PDF                                      |
| `transfer_verify_payee`         | Verify a payee (Verification of Payee / VoP)                          |
| `transfer_bulk_verify_payee`    | Bulk verify payees (VoP)                                              |
| **Internal Transfers**          |                                                                       |
| `internal_transfer_create`      | Create an internal transfer between two bank accounts                 |
| **Bulk Transfers**              |                                                                       |
| `bulk_transfer_list`            | List bulk transfers                                                   |
| `bulk_transfer_show`            | Show details of a specific bulk transfer                              |
| `bulk_transfer_create`