@promptpartner/bexio-mcp-server 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bexio MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @promptpartner/bexio-mcp-server
+
+Complete Swiss accounting integration for [Bexio](https://www.bexio.com/) with [Claude Desktop](https://claude.com/desktop). Manage invoices, contacts, projects, time tracking, and 200+ more tools through natural conversation.
+
+## Quick Start
+
+### Option 1: MCPB Bundle (Recommended)
+
+1. Download `bexio-mcp-server.mcpb` from [Releases](https://github.com/promptpartner/bexio-mcp-server/releases)
+2. Double-click to install in Claude Desktop
+3. Enter your Bexio API token when prompted
+
+### Option 2: npm
+
+```bash
+npx @promptpartner/bexio-mcp-server
+```
+
+Add to Claude Desktop config:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "bexio": {
+      "command": "npx",
+      "args": ["@promptpartner/bexio-mcp-server"],
+      "env": {
+        "BEXIO_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### Option 3: From Source
+
+```bash
+git clone https://github.com/promptpartner/bexio-mcp-server
+cd bexio-mcp-server/src
+npm install
+npm run build
+```
+
+Add to Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "bexio": {
+      "command": "node",
+      "args": ["/path/to/bexio-mcp-server/src/dist/index.js"],
+      "env": {
+        "BEXIO_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Getting Your Bexio API Token
+
+1. Log in to [Bexio](https://office.bexio.com/)
+2. Go to **Settings** > **API Tokens**
+3. Click **Create Token**
+4. Copy the token and use it in your configuration
+
+## Features
+
+This MCP server provides **221 tools** across all Bexio domains:
+
+### Contacts & CRM
+- Create, update, search contacts
+- Contact groups, sectors, salutations, titles
+- Contact relations management
+
+### Invoices & Sales
+- Full invoice lifecycle (create, issue, send, cancel)
+- Quotes with accept/decline workflows
+- Orders with delivery management
+- Incoming payments tracking
+- Interactive invoice preview
+
+### Banking & Payments
+- Swiss QR-bill payment support (QR-IBAN)
+- Standard IBAN payments (ISO 20022)
+- Currency management (CHF, EUR)
+- Bank account management
+
+### Projects & Time Tracking
+- Project management with types and statuses
+- Milestones and work packages
+- Timesheet entries with duration tracking
+- Business activities and communication types
+
+### Accounting
+- Chart of accounts
+- Manual journal entries
+- Business years and VAT periods
+- Account groups
+
+### Purchase & Expenses
+- Bills (creditor invoices)
+- Expenses and purchase orders
+- Outgoing payments
+
+### Files & Documents
+- Document upload/download
+- File management
+
+### Payroll (requires Bexio Payroll module)
+- Employee management
+- Absence tracking
+- Payroll documents
+
+## HTTP Mode
+
+For integration with n8n or other automation tools:
+
+```bash
+npx @promptpartner/bexio-mcp-server --mode http --port 8000
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BEXIO_API_TOKEN` | Yes | - | Your Bexio API token |
+| `BEXIO_BASE_URL` | No | `https://api.bexio.com/2.0` | API endpoint URL |
+
+## Troubleshooting
+
+### "Invalid API token" error
+- Verify your token in Bexio Settings > API Tokens
+- Ensure the token has not expired
+- Check that the token has the required permissions
+
+### "Connection refused" error
+- Check your internet connection
+- Verify BEXIO_BASE_URL is correct (default: https://api.bexio.com/2.0)
+
+### Payroll tools return "module not available"
+- Payroll tools require the Bexio Payroll module subscription
+- Contact Bexio support to enable the module
+
+### Claude Desktop doesn't see the server
+- Restart Claude Desktop after configuration changes
+- Verify the config file path is correct for your OS
+- Check Claude Desktop logs for error messages
+
+## License
+
+MIT - See [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Bexio API Documentation](https://docs.bexio.com/)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+- [Report Issues](https://github.com/promptpartner/bexio-mcp-server/issues)

package/dist/bexio-client.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Bexio API Client.
+ * Handles all HTTP communication with the Bexio API.
+ * Uses logger for all output (no console.log).
+ */
+import { BexioConfig, PaginationParams, ContactSearchParams, InvoiceSearchParams, InvoiceCreate, OrderCreate, SearchCriteria } from "./types/index.js";
+export declare class BexioClient {
+    private client;
+    private config;
+    constructor(config: BexioConfig);
+    private makeRequest;
+    listContactGroups(params?: PaginationParams): Promise<unknown[]>;
+    getContactGroup(groupId: number): Promise<unknown>;
+    createContactGroup(data: {
+        name: string;
+    }): Promise<unknown>;
+    deleteContactGroup(groupId: number): Promise<unknown>;
+    listContactSectors(params?: PaginationParams): Promise<unknown[]>;
+    getContactSector(sectorId: number): Promise<unknown>;
+    createContactSector(data: {
+        name: string;
+    }): Promise<unknown>;
+    listSalutations(params?: PaginationParams): Promise<unknown[]>;
+    getSalutation(salutationId: number): Promise<unknown>;
+    createSalutation(data: {
+        name: string;
+    }): Promise<unknown>;
+    deleteSalutation(salutationId: number): Promise<unknown>;
+    listTitles(params?: PaginationParams): Promise<unknown[]>;
+    getTitle(titleId: number): Promise<unknown>;
+    createTitle(data: {
+        name: string;
+    }): Promise<unknown>;
+    deleteTitle(titleId: number): Promise<unknown>;
+    listCountries(params?: PaginationParams): Promise<unknown[]>;
+    getCountry(countryId: number): Promise<unknown>;
+    createCountry(data: {
+        name: string;
+        iso_3166_alpha2: string;
+    }): Promise<unknown>;
+    deleteCountry(countryId: number): Promise<unknown>;
+    listLanguages(params?: PaginationParams): Promise<unknown[]>;
+    getLanguage(languageId: number): Promise<unknown>;
+    createLanguage(data: {
+        name: string;
+        iso_639_1: string;
+    }): Promise<unknown>;
+    listUnits(params?: PaginationParams): Promise<unknown[]>;
+    getUnit(unitId: number): Promise<unknown>;
+    createUnit(data: {
+        name: string;
+    }): Promise<unknown>;
+    deleteUnit(unitId: number): Promise<unknown>;
+    getCompanyProfile(): Promise<unknown>;
+    updateCompanyProfile(data: Record<string, unknown>): Promise<unknown>;
+    listPermissions(): Promise<unknown>;
+    listPaymentTypes(params?: PaginationParams): Promise<unknown[]>;
+    getPaymentType(paymentTypeId: number): Promise<unknown>;
+    createPaymentType(data: {
+        name: string;
+    }): Promise<unknown>;
+    listBankAccounts(params?: PaginationParams): Promise<unknown[]>;
+    getBankAccount(accountId: number): Promise<unknown>;
+    listCurrencies(params?: PaginationParams): Promise<unknown[]>;
+    getCurrency(currencyId: number): Promise<unknown>;
+    createCurrency(data: {
+        name: string;
+        round_factor: number;
+    }): Promise<unknown>;
+    updateCurrency(currencyId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteCurrency(currencyId: number): Promise<unknown>;
+    createIbanPayment(data: {
+        bank_account_id: number;
+        iban: string;
+        instructed_amount: {
+            currency: string;
+            amount: number;
+        };
+        recipient: {
+            name: string;
+            street?: string;
+            house_number?: string;
+            zip: string;
+            city: string;
+            country_code: string;
+        };
+        execution_date: string;
+        message?: string;
+        is_salary_payment?: boolean;
+        allowance_type?: string;
+    }): Promise<unknown>;
+    getIbanPayment(paymentId: number): Promise<unknown>;
+    updateIbanPayment(paymentId: number, data: Record<string, unknown>): Promise<unknown>;
+    createQrPayment(data: {
+        bank_account_id: number;
+        iban: string;
+        instructed_amount: {
+            currency: string;
+            amount: number;
+        };
+        recipient: {
+            name: string;
+            street?: string;
+            house_number?: string;
+            zip: string;
+            city: string;
+            country_code: string;
+        };
+        execution_date: string;
+        qr_reference_nr?: string;
+        additional_information?: string;
+    }): Promise<unknown>;
+    getQrPayment(paymentId: number): Promise<unknown>;
+    updateQrPayment(paymentId: number, data: Record<string, unknown>): Promise<unknown>;
+    listOrders(params?: PaginationParams): Promise<unknown[]>;
+    getOrder(orderId: number): Promise<unknown>;
+    createOrder(orderData: OrderCreate): Promise<unknown>;
+    searchOrders(searchParams: Record<string, unknown>): Promise<unknown[]>;
+    searchOrdersByContactId(contactId: number): Promise<unknown[]>;
+    createDeliveryFromOrder(orderId: number): Promise<unknown>;
+    createInvoiceFromOrder(orderId: number): Promise<unknown>;
+    listContacts(params?: ContactSearchParams): Promise<unknown[]>;
+    getContact(contactId: number): Promise<unknown>;
+    searchContacts(query: string, limit?: number): Promise<unknown[]>;
+    advancedSearchContacts(searchCriteria: SearchCriteria[], limit?: number): Promise<unknown[]>;
+    findContactByNumber(contactNumber: string): Promise<unknown>;
+    findContactByName(name: string): Promise<unknown[]>;
+    updateContact(contactId: number, contactData: Record<string, unknown>): Promise<unknown>;
+    createQuote(quoteData: Record<string, unknown>): Promise<unknown>;
+    listQuotes(params?: PaginationParams): Promise<unknown[]>;
+    getQuote(quoteId: number): Promise<unknown>;
+    searchQuotes(searchParams: Record<string, unknown>): Promise<unknown[]>;
+    searchQuotesByContactId(contactId: number): Promise<unknown[]>;
+    issueQuote(quoteId: number): Promise<unknown>;
+    acceptQuote(quoteId: number): Promise<unknown>;
+    declineQuote(quoteId: number): Promise<unknown>;
+    sendQuote(quoteId: number): Promise<unknown>;
+    createOrderFromQuote(quoteId: number): Promise<unknown>;
+    createInvoiceFromQuote(quoteId: number): Promise<unknown>;
+    listInvoices(params?: PaginationParams): Promise<unknown[]>;
+    getInvoice(invoiceId: number): Promise<unknown>;
+    createInvoice(invoiceData: InvoiceCreate): Promise<unknown>;
+    listAllInvoices(chunkSize?: number): Promise<unknown[]>;
+    searchInvoices(params: InvoiceSearchParams): Promise<unknown[]>;
+    issueInvoice(invoiceId: number): Promise<unknown>;
+    cancelInvoice(invoiceId: number): Promise<unknown>;
+    markInvoiceAsSent(invoiceId: number): Promise<unknown>;
+    sendInvoice(invoiceId: number): Promise<unknown>;
+    copyInvoice(invoiceId: number): Promise<unknown>;
+    listTaxes(params?: PaginationParams): Promise<unknown[]>;
+    getTax(taxId: number): Promise<unknown>;
+    listItems(params?: PaginationParams): Promise<unknown[]>;
+    getItem(itemId: number): Promise<unknown>;
+    createItem(itemData: Record<string, unknown>): Promise<unknown>;
+    listDeliveries(params?: PaginationParams): Promise<unknown[]>;
+    getDelivery(deliveryId: number): Promise<unknown>;
+    issueDelivery(deliveryId: number): Promise<unknown>;
+    searchDeliveries(searchParams: Record<string, unknown>): Promise<unknown[]>;
+    listPayments(invoiceId: number): Promise<unknown[]>;
+    createPayment(invoiceId: number, paymentData: Record<string, unknown>): Promise<unknown>;
+    getPayment(invoiceId: number, paymentId: number): Promise<unknown>;
+    deletePayment(invoiceId: number, paymentId: number): Promise<unknown>;
+    listReminders(invoiceId: number): Promise<unknown[]>;
+    createReminder(invoiceId: number, reminderData: Record<string, unknown>): Promise<unknown>;
+    getReminder(invoiceId: number, reminderId: number): Promise<unknown>;
+    deleteReminder(invoiceId: number, reminderId: number): Promise<unknown>;
+    markReminderAsSent(invoiceId: number, reminderId: number): Promise<unknown>;
+    sendReminder(invoiceId: number, reminderId: number): Promise<unknown>;
+    listContactRelations(): Promise<unknown[]>;
+    createContactRelation(relationData: Record<string, unknown>): Promise<unknown>;
+    getContactRelation(relationId: number): Promise<unknown>;
+    updateContactRelation(relationId: number, relationData: Record<string, unknown>): Promise<unknown>;
+    deleteContactRelation(relationId: number): Promise<unknown>;
+    searchContactRelations(searchParams: Record<string, unknown>): Promise<unknown[]>;
+    getCurrentUser(): Promise<unknown>;
+    listFictionalUsers(params?: PaginationParams): Promise<unknown[]>;
+    getFictionalUser(userId: number): Promise<unknown>;
+    createFictionalUser(userData: Record<string, unknown>): Promise<unknown>;
+    updateFictionalUser(userId: number, userData: Record<string, unknown>): Promise<unknown>;
+    deleteFictionalUser(userId: number): Promise<unknown>;
+    listComments(): Promise<unknown[]>;
+    getComment(commentId: number): Promise<unknown>;
+    createComment(commentData: Record<string, unknown>): Promise<unknown>;
+    searchReminders(searchParams: Record<string, unknown>): Promise<unknown[]>;
+    getRemindersSentThisWeek(): Promise<unknown[]>;
+    getRevenueReport(startDate: string, endDate: string, groupBy?: string): Promise<unknown>;
+    getCustomerRevenueReport(startDate: string, endDate: string, limit?: number): Promise<unknown[]>;
+    getInvoiceStatusReport(startDate: string, endDate: string): Promise<unknown>;
+    getOverdueInvoicesReport(): Promise<unknown[]>;
+    getMonthlyRevenueReport(year: number, month: number): Promise<unknown>;
+    getTopCustomersByRevenue(limit?: number, startDate?: string, endDate?: string): Promise<unknown[]>;
+    getOpenInvoices(): Promise<unknown[]>;
+    getOverdueInvoices(): Promise<unknown[]>;
+    getTasksDueThisWeek(): Promise<unknown[]>;
+    listInvoiceStatuses(): Promise<unknown[]>;
+    listAllStatuses(documentType?: "all" | "invoices" | "quotes" | "orders"): Promise<unknown[]>;
+    listProjects(params?: PaginationParams): Promise<unknown[]>;
+    getProject(projectId: number): Promise<unknown>;
+    createProject(data: {
+        user_id: number;
+        name: string;
+        contact_id?: number;
+        pr_state_id?: number;
+        pr_project_type_id?: number;
+        start_date?: string;
+        end_date?: string;
+        comment?: string;
+    }): Promise<unknown>;
+    updateProject(projectId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteProject(projectId: number): Promise<unknown>;
+    archiveProject(projectId: number): Promise<unknown>;
+    unarchiveProject(projectId: number): Promise<unknown>;
+    searchProjects(searchParams: Record<string, unknown>[]): Promise<unknown[]>;
+    listProjectTypes(params?: PaginationParams): Promise<unknown[]>;
+    getProjectType(typeId: number): Promise<unknown>;
+    listProjectStatuses(params?: PaginationParams): Promise<unknown[]>;
+    getProjectStatus(statusId: number): Promise<unknown>;
+    listMilestones(projectId: number, params?: PaginationParams): Promise<unknown[]>;
+    getMilestone(projectId: number, milestoneId: number): Promise<unknown>;
+    createMilestone(projectId: number, data: {
+        name: string;
+        end_date?: string;
+    }): Promise<unknown>;
+    deleteMilestone(projectId: number, milestoneId: number): Promise<unknown>;
+    listWorkPackages(projectId: number, params?: PaginationParams): Promise<unknown[]>;
+    getWorkPackage(projectId: number, workpackageId: number): Promise<unknown>;
+    createWorkPackage(projectId: number, data: {
+        name: string;
+        estimated_time?: string;
+    }): Promise<unknown>;
+    updateWorkPackage(projectId: number, workpackageId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteWorkPackage(projectId: number, workpackageId: number): Promise<unknown>;
+    listTimesheets(params?: PaginationParams): Promise<unknown[]>;
+    getTimesheet(timesheetId: number): Promise<unknown>;
+    createTimesheet(data: {
+        user_id: number;
+        date: string;
+        duration: string;
+        pr_project_id?: number;
+        pr_package_id?: number;
+        pr_milestone_id?: number;
+        client_service_id?: number;
+        text?: string;
+        allowable_bill?: boolean;
+    }): Promise<unknown>;
+    deleteTimesheet(timesheetId: number): Promise<unknown>;
+    searchTimesheets(searchParams: Record<string, unknown>[]): Promise<unknown[]>;
+    listTimesheetStatuses(): Promise<unknown[]>;
+    listBusinessActivities(params?: PaginationParams): Promise<unknown[]>;
+    getBusinessActivity(activityId: number): Promise<unknown>;
+    createBusinessActivity(data: {
+        name: string;
+    }): Promise<unknown>;
+    listCommunicationTypes(params?: PaginationParams): Promise<unknown[]>;
+    getCommunicationType(typeId: number): Promise<unknown>;
+    listAccounts(params?: PaginationParams): Promise<unknown[]>;
+    getAccount(accountId: number): Promise<unknown>;
+    createAccount(data: {
+        account_no: number;
+        name: string;
+        account_group_id: number;
+        is_active?: boolean;
+        tax_id?: number;
+    }): Promise<unknown>;
+    searchAccounts(searchParams: Record<string, unknown>[]): Promise<unknown[]>;
+    listAccountGroups(params?: PaginationParams): Promise<unknown[]>;
+    listCalendarYears(params?: PaginationParams): Promise<unknown[]>;
+    getCalendarYear(yearId: number): Promise<unknown>;
+    listBusinessYears(params?: PaginationParams): Promise<unknown[]>;
+    listManualEntries(params?: PaginationParams): Promise<unknown[]>;
+    getManualEntry(entryId: number): Promise<unknown>;
+    createManualEntry(data: {
+        type: string;
+        date: string;
+        reference_nr?: string;
+        entries: Array<{
+            debit_account_id: number;
+            credit_account_id: number;
+            tax_id?: number;
+            tax_account_id?: number;
+            description: string;
+            amount: number;
+            currency_id?: number;
+            currency_factor?: number;
+        }>;
+    }): Promise<unknown>;
+    updateManualEntry(entryId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteManualEntry(entryId: number): Promise<unknown>;
+    listVatPeriods(params?: PaginationParams): Promise<unknown[]>;
+    getJournal(params: {
+        start_date?: string;
+        end_date?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown[]>;
+    listBills(params?: PaginationParams): Promise<unknown[]>;
+    getBill(billId: number): Promise<unknown>;
+    createBill(data: Record<string, unknown>): Promise<unknown>;
+    updateBill(billId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteBill(billId: number): Promise<unknown>;
+    searchBills(searchParams: Record<string, unknown>[], queryParams?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown[]>;
+    issueBill(billId: number): Promise<unknown>;
+    markBillAsPaid(billId: number): Promise<unknown>;
+    listExpenses(params?: PaginationParams): Promise<unknown[]>;
+    getExpense(expenseId: number): Promise<unknown>;
+    createExpense(data: Record<string, unknown>): Promise<unknown>;
+    updateExpense(expenseId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteExpense(expenseId: number): Promise<unknown>;
+    listPurchaseOrders(params?: PaginationParams): Promise<unknown[]>;
+    getPurchaseOrder(purchaseOrderId: number): Promise<unknown>;
+    createPurchaseOrder(data: Record<string, unknown>): Promise<unknown>;
+    updatePurchaseOrder(purchaseOrderId: number, data: Record<string, unknown>): Promise<unknown>;
+    deletePurchaseOrder(purchaseOrderId: number): Promise<unknown>;
+    listOutgoingPayments(billId: number): Promise<unknown[]>;
+    getOutgoingPayment(billId: number, paymentId: number): Promise<unknown>;
+    createOutgoingPayment(billId: number, paymentData: Record<string, unknown>): Promise<unknown>;
+    updateOutgoingPayment(billId: number, paymentId: number, paymentData: Record<string, unknown>): Promise<unknown>;
+    deleteOutgoingPayment(billId: number, paymentId: number): Promise<unknown>;
+    listEmployees(params?: PaginationParams): Promise<unknown[]>;
+    getEmployee(employeeId: number): Promise<unknown>;
+    createEmployee(data: Record<string, unknown>): Promise<unknown>;
+    updateEmployee(employeeId: number, data: Record<string, unknown>): Promise<unknown>;
+    listAbsences(params?: PaginationParams & {
+        year?: number;
+    }): Promise<unknown[]>;
+    getAbsence(absenceId: number): Promise<unknown>;
+    createAbsence(data: Record<string, unknown>): Promise<unknown>;
+    updateAbsence(absenceId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteAbsence(absenceId: number): Promise<unknown>;
+    listPayrollDocuments(params?: PaginationParams & {
+        employee_id?: number;
+    }): Promise<unknown[]>;
+    listFiles(params?: PaginationParams): Promise<unknown[]>;
+    getFile(fileId: number): Promise<unknown>;
+    uploadFile(data: {
+        name: string;
+        content_base64: string;
+        content_type: string;
+    }): Promise<unknown>;
+    downloadFile(fileId: number): Promise<string>;
+    updateFile(fileId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteFile(fileId: number): Promise<unknown>;
+    listAdditionalAddresses(contactId: number, params?: PaginationParams): Promise<unknown[]>;
+    getAdditionalAddress(contactId: number, addressId: number): Promise<unknown>;
+    createAdditionalAddress(contactId: number, data: Record<string, unknown>): Promise<unknown>;
+    deleteAdditionalAddress(contactId: number, addressId: number): Promise<unknown>;
+}