Bexio MCP Server Demo

MCP server for Bexio ERP integration - enables AI assistants to interact with Bexio business management software.

Available in FlowHunt.io - Test this MCP server directly in FlowHunt's no-code AI automation platform with visual drag-and-drop workflow builder.

Features

• 🔍 Contact Management: Search, create, update, and manage contacts

• 📄 Invoice Operations: Create, search, and manage invoices

• 💰 Quote Management: Handle quotes and proposals

• 🏗️ Project Management: Create and track projects

• 📦 Item/Article Management: Manage products and services

• 🔐 Secure Authentication: Uses Bexio Personal Access Tokens (PAT)

• ✅ Smart Field Validation: Automatic field completion and 422 error prevention

• 🛡️ Enhanced Error Handling: Clear guidance for missing or invalid fields

Related MCP server: bexio-mcp-server

Installation

Prerequisites

• Python 3.10+

• Bexio account with API access

Install

• For users:

pip install .

• For development (with tests and linters):

pip install -e ".[dev]"

Configuration

Getting Your Bexio Access Token

The easiest way to get an access token is using Personal Access Tokens (PAT):

1. Visit https://developer.bexio.com/pat

2. Create a new Personal Access Token

3. Copy the token (it will look like: eyJraWQiOiI2ZGM2YmJlOC1iMjZjLTExZTgtOGUwZC0w...)

PAT Benefits:

• ✅ Full access to your company's data

• ✅ Valid for 6 months

• ✅ No OAuth setup required

• ✅ Perfect for personal/development use

Alternative Authentication

If you need custom scopes or multi-user access beyond Personal Access Tokens (PAT), implement an OAuth flow in your own application using Bexio's OAuth documentation.

Environment Setup

Create a .env file in your project directory:

BEXIO_ACCESS_TOKEN=your_personal_access_token_here
BEXIO_API_URL=https://api.bexio.com/2.0
BEXIO_TIMEOUT=120

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bexio": {
      "command": "python",
      "args": ["-m", "mcp_server_bexio.server"],
      "cwd": "/path/to/your/bexio-mcp-server",
      "env": {
        "BEXIO_ACCESS_TOKEN": "YOUR_NEW_PAT_TOKEN_HERE"
      }
    }
  }
}

Important: Replace YOUR_NEW_PAT_TOKEN_HERE with your actual Personal Access Token from https://developer.bexio.com/pat

Available Tools

Contact Management

search_contacts

Search for contacts using criteria. Parameters:

• criteria (required): Array of search criteria objects with field/value/criteria

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

Example prompts:

• "Find all contacts with email containing 'gmail.com'"

• "Search for companies in Zurich"

• "Show me contacts created this month"

get_contact

Get detailed information about a specific contact. Parameters:

• contact_id (required): Contact ID

create_contact

Create a new contact. Required fields:

• name_1: First name or company name Auto-filled fields (can be overridden):

• contact_type_id: Contact type (default: 2 for person)

• user_id: User ID (default: 1)

• owner_id: Owner ID (default: 1)

update_contact

Update an existing contact. Required fields:

• contact_id: Contact ID Auto-retrieved fields:

• name_1, contact_type_id, user_id, owner_id, nr: Retrieved from existing contact

list_contacts

List all contacts with optional filtering. Parameters:

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

• order_by: Field to order by (optional)

Invoice Management

search_invoices

Search for invoices using criteria. Parameters:

• criteria (required): Array of search criteria objects with field/value/criteria

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

get_invoice

Get detailed information about a specific invoice. Parameters:

• invoice_id (required): Invoice ID

create_invoice

Create a new invoice. Required fields:

• contact_id: Contact ID for the invoice

• positions: Array with line items (each needs text description) Auto-filled fields (can be overridden):

• user_id: User ID (default: 1)

• nr: Invoice number (API auto-generates)

• Position fields: type, amount, unit_price, tax_id (default: Tax ID 3 - 0% rate)

Note: Uses flat schema structure for consistent UI experience.

list_invoices

List all invoices with optional filtering. Parameters:

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

• order_by: Field to order by (optional)

Quote Management

search_quotes

Search for quotes using criteria. Parameters:

• criteria (required): Array of search criteria objects with field/value/criteria

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

get_quote

Get detailed information about a specific quote. Parameters:

• quote_id (required): Quote ID

create_quote

Create a new quote. Required fields:

• contact_id: Contact ID for the quote Auto-filled fields (can be overridden):

• user_id: User ID (default: 1)

• nr: Quote number (API auto-generates)

• Positions: Optional but recommended, same auto-fill as invoices

Note: Uses flat schema structure for consistent UI experience.

Project Management

list_projects

List all projects with optional filtering. Parameters:

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

• order_by: Field to order by (optional)

get_project

Get detailed information about a specific project. Parameters:

• project_id (required): Project ID

create_project

Create a new project. Required fields:

• name: Project name

• contact_id: Contact ID for the project Auto-filled fields (can be overridden):

• user_id: User ID (default: 1)

• nr: Project number (API auto-generates)

• pr_state_id: Project state ID (default: 1)

• pr_project_type_id: Project type ID (default: 1)

Item/Article Management

list_items

List all items/articles with optional filtering. Parameters:

• limit: Maximum number of results (auto-filled: 50)

• offset: Number of records to skip (auto-filled: 0)

• order_by: Field to order by (optional)

get_item

Get detailed information about a specific item. Parameters:

• item_id (required): Item ID

create_item

Create a new item/article. Required fields:

• intern_name: Internal item name Auto-filled fields (can be overridden):

• user_id: User ID (default: 1)

• nr: Item number (API auto-generates)

• article_type_id: Article type ID (default: 1)

• currency_id: Currency ID (default: 1)

• is_stock: Stock item flag (default: false)

• delivery_price: Delivery price (default: 0)

Common Use Cases

Customer Management

• Search and filter customer contacts

• Create new customer records

• Update customer information

• Track customer communication history

Sales Operations

• Create and manage quotes

• Convert quotes to orders and invoices

• Track sales pipeline

• Generate sales reports

Project Management

• Create and track projects

• Assign projects to customers

• Monitor project progress

• Manage project timesheets

Inventory Management

• Manage product catalog

• Track stock levels

• Update pricing information

• Handle product variations

Security Considerations

• Store your Bexio access token securely

• Use environment variables for sensitive configuration

• Regularly rotate access tokens

• Monitor API usage and access logs

• Implement proper error handling for API failures

Smart Field Validation

This MCP server includes intelligent field validation to prevent common 422 errors and improve user experience:

Automatic Field Completion

• Required fields: Prompts users for critical missing information

• Safe defaults: Auto-fills non-critical fields (user_id, project states, etc.)

• Dynamic lookups: Retrieves existing data for updates (contact numbers, tax IDs)

• API-aware: Skips fields where Bexio API provides intelligent defaults

Enhanced Error Handling

• Pre-validation: Catches missing fields before API calls

• Clear guidance: Specific error messages explaining what's needed

• Smart tax handling: Automatically looks up valid tax IDs from your Bexio system

• Field-specific help: Distinguishes between missing vs invalid field values

Field Types

• REQUIRED_USER_INPUT: Critical fields requiring user input (contact names, IDs)

• AUTO_FILL_DEFAULT: Safe defaults (user_id=1, project_state_id=1) - can be overridden by user

• AUTO_FILL_LOOKUP: Retrieved from existing data (for updates)

• API_HANDLED: Fields where API provides fallback handling

User Override Capability

Important: All auto-filled fields can be overridden by providing explicit values. The system only fills missing fields - if you specify a value, it will be used instead of the default.

Detailed Field Requirements

Contact Functions

create_contact:

• REQUIRED: name_1 (first name or company name)

• AUTO-FILLED: contact_type_id=2, user_id=1, owner_id=1

• OPTIONAL: email, phone, address, city, country_id, language_id

update_contact:

• REQUIRED: contact_id

• AUTO-RETRIEVED: name_1, contact_type_id, user_id, owner_id from existing contact

• OPTIONAL: All other contact fields

Invoice Functions

create_invoice:

• REQUIRED: contact_id, positions array

• AUTO-FILLED: user_id=1

• POSITION REQUIREMENTS: Each position needs text (description)

• AUTO-FILLED PER POSITION: type='KbPositionCustom', amount=1, unit_price=0.0, tax_id (looked up)

Quote Functions

create_quote:

• REQUIRED: contact_id

• AUTO-FILLED: user_id=1

• POSITIONS: Optional but recommended, same auto-fill rules as invoices

Project Functions

create_project:

• REQUIRED: name, contact_id

• AUTO-FILLED: user_id=1, pr_state_id=1, pr_project_type_id=1

Item Functions

create_item:

• REQUIRED: intern_name (internal item name)

• AUTO-FILLED: user_id=1, article_type_id=1, currency_id=1, is_stock=false, delivery_price=0

Validation Flow

1. Pre-validation: Check for truly required user input fields

2. Auto-completion: Fill missing fields with safe defaults or lookups

3. API call: Submit completed data to Bexio API

4. Error enhancement: Provide helpful guidance if validation still fails

5. Retry logic: Automatic retry for recoverable validation errors

Troubleshooting

422 Field Validation Errors

• Enhanced handling: The server now provides specific guidance for missing fields

• Auto-completion: Many required fields are filled automatically with safe defaults

• Tax ID issues: System automatically looks up valid tax IDs from your Bexio account

• Contact updates: Required fields like nr are retrieved from existing contact data

401 Authentication Failed

• Most common issue: Your Personal Access Token has expired (PAT tokens are valid for 6 months)

• Solution: Visit https://developer.bexio.com/pat and create a new token

• Update your .env file and Claude Desktop configuration with the new token

• Restart Claude Desktop after updating the configuration

Connection Issues

• Check your internet connection

• Verify the Bexio API is accessible

• Ensure no firewall restrictions

Rate Limiting

• Bexio API has rate limits - the server implements automatic retry logic

• Large result sets use pagination automatically

• Monitor API usage in your Bexio developer dashboard

Project Structure

bexio-mcp-server/
├── mcp_server_bexio/
│   ├── __init__.py
│   ├── server.py
│   ├── bexio_client.py
│   └── field_validator.py
├── pyproject.toml
└── README.md

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: https://github.com/tomasbottlik/bexio-mcp-server/issues

• Bexio API Documentation: https://docs.bexio.com/

About

This MCP server enables seamless integration between AI assistants and Bexio business management software, allowing for natural language interaction with your business data.