BillbeeMcpServer

Disclaimer: This is an independent, private project and is not an official Billbee product or affiliated with Billbee GmbH in any way. Use at your own risk.

A C# MCP (Model Context Protocol) server that exposes the Billbee REST API as MCP tools for use with Claude Desktop, VS Code Copilot, Cursor, and other MCP-compatible AI assistants.

All 69 tools are implemented as direct HTTP calls against https://app.billbee.io — no intermediate SDK dependency.

---

Features

• 69 MCP tools covering Orders, Products, Customers, Shipments, Events, Search, Enums, and API Usage
• Proactive rate limiting — enforces Billbee's 10 req/s per API key + user limit using a token bucket
• Automatic retry — retries on HTTP 429 (Too Many Requests) and 5xx errors with exponential backoff, honouring the Retry-After header
• Credential security — credentials are never hardcoded; use environment variables (production) or .NET User Secrets (development)
• stdio transport — integrates natively with any MCP-compatible client

---

Prerequisites

• .NET 9 SDK
• A Billbee account with API access enabled (contact Billbee support to activate)
• Your Billbee credentials:
  • API Key — found in Billbee under Settings → API
  • Username — your Billbee account e-mail address
  • API Password — your Billbee API password (not your login password; set separately under Settings → API)

---

Environment Variables

Variable	Description
BILLBEE_API_KEY	Your Billbee API key (sent as X-Billbee-Api-Key header)
BILLBEE_USERNAME	Your Billbee account e-mail
BILLBEE_PASSWORD	Your Billbee API password

---

Development Setup (User Secrets)

For local development, use .NET User Secrets to avoid storing credentials in environment variables or files:

cd BillbeeMcpServer
dotnet user-secrets set "API_KEY" "your-api-key-here"
dotnet user-secrets set "USERNAME" "your@email.com"
dotnet user-secrets set "PASSWORD" "your-api-password-here"

User Secrets are only used when BILLBEE_* environment variables are not set.

---

Building

dotnet build BillbeeMcpServer.sln

---

Claude Desktop Integration

Add the following snippet to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Option A: Run a published binary (recommended)

Claude Desktop launches processes with a minimal PATH that typically does not include the dotnet runtime. Publishing a self-contained binary avoids this problem entirely and also starts faster.

First, publish the server:

dotnet publish src/BillbeeMcpServer.csproj -c Release -r osx-arm64 --self-contained -o ./publish
# Replace osx-arm64 with your platform: win-x64, linux-x64, osx-x64

Then configure Claude Desktop:

{
  "mcpServers": {
    "billbee": {
      "command": "/absolute/path/to/publish/BillbeeMcpServer",
      "args": [],
      "env": {
        "BILLBEE_API_KEY": "your-api-key-here",
        "BILLBEE_USERNAME": "your@email.com",
        "BILLBEE_PASSWORD": "your-api-password-here"
      }
    }
  }
}

Option B: Run from source (development, macOS/Linux)

Note: Claude Desktop uses a restricted PATH. If dotnet is not in /usr/local/bin, /opt/homebrew/bin, or similar standard locations, you must use the full path to the dotnet executable (e.g. /usr/local/share/dotnet/dotnet on macOS).

{
  "mcpServers": {
    "billbee": {
      "command": "/usr/local/share/dotnet/dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/repo/src/BillbeeMcpServer.csproj",
        "--no-build"
      ],
      "env": {
        "BILLBEE_API_KEY": "your-api-key-here",
        "BILLBEE_USERNAME": "your@email.com",
        "BILLBEE_PASSWORD": "your-api-password-here"
      }
    }
  }
}

---

VS Code / Cursor Integration

Add to your workspace .vscode/mcp.json or user-level MCP settings:

{
  "servers": {
    "billbee": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/repo/src/BillbeeMcpServer.csproj",
        "--no-build"
      ],
      "env": {
        "BILLBEE_API_KEY": "your-api-key-here",
        "BILLBEE_USERNAME": "your@email.com",
        "BILLBEE_PASSWORD": "your-api-password-here"
      }
    }
  }
}

---

Available Tools (69)

Orders (18)

Tool	Description
GetOrders	List orders with date, state, tag, and shop filters
GetOrder	Get a single order by Billbee ID
GetOrderByExternalRef	Find an order by marketplace reference number
GetPatchableOrderFields	List fields that can be partially updated
PatchOrder	Partially update specific order fields
CreateOrder	Create a new order
CreateMultipleOrders	Create multiple orders in one request
UpdateOrderState	Change order state (use GetOrderStateEnums for IDs)
AddOrderTags	Add tags to an order
UpdateOrderTags	Replace all tags on an order
AddShipmentToOrder	Attach a manual shipment record to an order
SendMessageToBuyer	Send a marketplace message to the buyer
AddInternalMessage	Add an internal note to an order
TriggerOrderEvent	Trigger an automation rule/event on an order
ParseOrderPlaceholders	Resolve text template placeholders for an order
CreateInvoice	Generate an invoice PDF for an order
CreateDeliveryNote	Generate a delivery note PDF for an order
GetInvoiceList	List invoices with optional filters

Products (22)

Tool	Description
GetProducts	List all products with pagination
GetProduct	Get a product by Billbee ID or SKU
CreateProduct	Create a new product
PatchProduct	Partially update a product
DeleteProduct	Delete a product
GetPatchableProductFields	List patchable product fields
GetProductCategories	List all product categories
GetStockLocations	List all warehouse/stock locations
UpdateProductStock	Update inventory for a single product
UpdateMultipleProductStocks	Update inventory for multiple products
GetReservedAmount	Get reserved/allocated inventory for a product
UpdateStockCode	Update the bin/location code for a product
GetCustomFieldDefinitions	List custom field definitions
GetCustomFieldDefinition	Get a single custom field definition
GetProductImages	List all images for a product
GetProductImage	Get a specific product image
GetImageById	Get an image by image ID
AddProductImage	Add or update a single product image
AddMultipleProductImages	Add or replace all images for a product
DeleteProductImage	Delete a specific product image
DeleteImageById	Delete an image by image ID
DeleteMultipleImages	Delete multiple images by ID list

Customers (10)

Tool	Description
GetCustomers	List all customers
GetCustomer	Get a customer by ID
CreateCustomer	Create a new customer
UpdateCustomer	Replace customer data
GetCustomerOrders	List orders for a customer
GetCustomerAddresses	List addresses for a customer
AddAddressToCustomer	Add an address to a customer
GetCustomerAddressById	Get a customer address by ID
UpdateCustomerAddress	Replace a customer address
PatchCustomerAddress	Partially update a customer address

Customer Addresses (4)

Tool	Description
GetAllCustomerAddresses	List all customer addresses globally
GetCustomerAddress	Get a customer address by ID
CreateCustomerAddress	Create a new customer address
UpdateCustomerAddressGlobal	Update a customer address globally

Shipments (5)

Tool	Description
GetShipments	List shipments with filters
GetShippingProviders	List configured shipping providers
GetShippingCarriers	List shipping carrier enumerations
CreateShipment	Create a shipment via a shipping provider
ShipOrderWithLabel	Ship an order and generate a label

Events (1)

Tool	Description
GetEvents	List system events with date and type filters

Search (1)

Tool	Description
Search	Full-text search across orders, products, and customers

Enums (6)

Tool	Description
GetPaymentTypes	List payment type enumerations
GetShippingCarrierEnums	List shipping carrier enumerations
GetShipmentTypeEnums	List shipment type enumerations
GetOrderStateEnums	List order state enumerations
GetAccountSyncStates	List account sync state enumerations
GetShopAccountTypes	List shop account type enumerations

API Usage (2)

Tool	Description
GetApiUsageSummary	Get summarized API usage statistics
GetApiUsageDetail	Get detailed API usage statistics

---

Rate Limiting

Billbee enforces:

• 50 req/s per API key
• 10 req/s per API key + user combination

This server proactively enforces the 10 req/s limit using a token bucket rate limiter. If Billbee returns HTTP 429, the server automatically waits for the duration specified in the Retry-After header and retries (up to 4 times with exponential backoff).

---

License

MIT