Bambuddy MCP Server

Bambuddy MCP Server

An MCP server that exposes the full Bambuddy REST API as tools for AI assistants.

This MCP server dynamically generates tools from Bambuddy's OpenAPI spec at startup, giving your AI assistant access to 430+ API endpoints — without flooding the context window on startup.

How It Works

On startup, the server fetches the OpenAPI spec from your running Bambuddy instance (/openapi.json), parses all 430+ endpoints, and indexes them by category.

By default, only 3 meta-tools are registered with the AI assistant:

| Meta-tool | Purpose | |-----------|---------| | list_categories | Browse available API categories | | search_tools | Find tools by keyword (with fuzzy matching) | | execute_tool | Call any discovered tool by name |

This keeps the context window small while still providing full API coverage. The AI searches for what it needs, inspects the input schema, and executes — all on demand.

When a tool is called, the server makes the corresponding HTTP request to Bambuddy and returns the response. JSON responses are returned as text, while binary responses (e.g. camera snapshots) are returned as native MCP ImageContent with base64-encoded data so AI assistants can see, process, and display them directly.

Example Usage

Once configured, you can ask your AI assistant things like:

• "What printers are connected?"
• "Show me the status of my A1 Mini"
• "List my recent print archives"
• "Add the benchy to the print queue"
• "What filament spools do I have?"
• "Check the print progress"
• "Turn on the chamber light"
• "Show me a camera snapshot from printer X"

Requirements

• Python 3.10+
• uv — install with curl -LsSf https://astral.sh/uv/install.sh | sh
• A running Bambuddy instance

Installation

uv pip install bambuddy-mcp

Or install from source:

git clone https://github.com/maziggy/bambuddy-mcp.git
cd bambuddy-mcp
uv sync

Configuration

Using uvx

{
  "mcpServers": {
    "bambuddy": {
      "command": "uvx",
      "args": ["bambuddy-mcp"],
      "env": {
        "BAMBUDDY_URL": "http://localhost:8000",
        "BAMBUDDY_API_KEY": "your-api-key",
        "BAMBUDDY_CENSOR_ACCESS_CODE": "true",
        "BAMBUDDY_CENSOR_SERIAL": "true",
        "BAMBUDDY_CENSOR_MODEL_FILENAME": "false"
      }
    }
  }
}

Local development

For development or running from source:

{
  "mcpServers": {
    "bambuddy": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bambuddy-mcp", "python", "-m", "bambuddy_mcp"],
      "env": {
        "BAMBUDDY_URL": "http://localhost:8000",
        "BAMBUDDY_API_KEY": "your-api-key",
        "BAMBUDDY_CENSOR_ACCESS_CODE": "true",
        "BAMBUDDY_CENSOR_SERIAL": "true",
        "BAMBUDDY_CENSOR_MODEL_FILENAME": "false"
      }
    }
  }
}

NixOS

On NixOS, use the system Python to avoid dynamic linking issues:

{
  "mcpServers": {
    "bambuddy": {
      "command": "nix-shell",
      "args": [
        "-p", "uv",
        "--run", "UV_PYTHON=/run/current-system/sw/bin/python3 uv --directory /path/to/bambuddy-mcp run bambuddy-mcp"
      ],
      "env": {
        "BAMBUDDY_URL": "http://localhost:8000",
        "BAMBUDDY_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | BAMBUDDY_URL | http://localhost:8000 | Base URL of your Bambuddy instance | | BAMBUDDY_API_KEY | _(empty)_ | API key for authentication (create in Bambuddy Settings) | | BAMBUDDY_DIRECT_MODE | false | Set to true to expose all 430+ tools directly instead of the meta-tools | | BAMBUDDY_CENSOR_ACCESS_CODE | true | Mask access_code fields in API responses | | BAMBUDDY_CENSOR_SERIAL | true | Mask serial_number fields (keeps first 2 + last 2 chars) | | BAMBUDDY_CENSOR_MODEL_FILENAME | false | Mask model filenames (.3mf, .gcode) in API responses and prevent direct base64 image embedding |

Note: By default, the server exposes meta-tools (list_categories, search_tools, execute_tool, find_printer) that let AI assistants discover and call API endpoints on demand. Set BAMBUDDY_DIRECT_MODE=true to expose all 430+ tools directly (uses significantly more context).