Bexio-MCP-Server

tbottlik/Bexio-MCP-Server

3.2

If you are the rightful owner of Bexio-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

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

Tools
18
Resources
0
Prompts
0

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

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:

About

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