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_K

... [View full README on GitHub](https://github.com/biegomar/BillbeeMcpServer#readme)