About Kiln

Overview

Kiln is the intelligence layer between idea and physical object. It provides a unified interface for AI agents to design, validate, and manufacture 3D-printed parts — controlling local printers, searching third-party model marketplaces (Thingiverse, MyMiniFactory, Cults3D), and routing jobs to fulfillment providers (Craftcloud) — all through the Model Context Protocol (MCP) or a 136-command CLI.

Clarification: Kiln does not operate its own marketplace or manufacturing network. It integrates with third-party marketplaces for model discovery and third-party fulfillment providers for outsourced manufacturing. Kiln is orchestration and agent infrastructure, not a supply-side platform.

Three ways to print:

  • 🖨️ Your printers. Control OctoPrint, Moonraker, Bambu Lab, or Prusa Link machines on your LAN — or remotely via Bambu Cloud.
  • 🏭 Fulfillment providers. Route to third-party fulfillment services like Craftcloud (150+ services — no API key required). No printer required — or use alongside local printers for overflow and specialty materials.
  • 🌐 External provider integrations. Route jobs through connected third-party provider APIs.

All three modes use the same MCP tools and CLI commands.

Non-goals:

  • Operating a first-party marketplace or manufacturing network
  • Replacing third-party supply-side platforms
  • Owning marketplaces instead of integrating with them
  • Acting as merchant of record for provider-routed manufacturing orders

Key properties:

  • Local-first. Local printer communication stays on your network. No cloud relay, no accounts, no telemetry.
  • Adapter-based. One interface covers OctoPrint, Moonraker, Bambu Lab, and Prusa Link. New backends plug in without changing upstream consumers.
  • Safety-enforced. Pre-flight checks, G-code validation, and temperature limits are protocol-level — not optional.
  • Agent-native. Every operation returns structured JSON. Every error includes machine-readable status codes. --json on every CLI command.

Supported Printers

Backend Protocol Printers Status
OctoPrint HTTP REST Any OctoPrint-connected printer Stable
Moonraker HTTP REST Klipper-based (Voron, RatRig, etc.) Stable
Bambu Lab MQTT/LAN X1C, P1S, A1 Stable
Prusa Link HTTP REST MK4, XL, Mini+ Stable
Elegoo WebSocket/SDCP Centauri Carbon, Saturn, Mars series. Neptune 4/OrangeStorm Giga use Moonraker. Stable

Key Concepts

PrinterAdapter — Abstract base class defining the contract for all printer backends. Implements: status, files, upload, print, cancel, pause, resume, temperature, G-code, snapshot.

PrinterStatus — Normalized enum: IDLE, PRINTING, PAUSED, ERROR, OFFLINE. Every backend maps its native state model to this enum.

MCP Tools — Typed functions exposed to agents via the Model Context Protocol. Each tool has a defined input schema and returns structured JSON.

MarketplaceAdapter — Abstract base class for searching third-party 3D model repositories. Implements: search, details, files, download. Concrete adapters for Thingiverse (deprecated — acquired by MyMiniFactory, Feb 2026), MyMiniFactory, and Cults3D (search only). Kiln does not host models — it searches external marketplaces.

MarketplaceRegistry — Manages connected marketplace adapters. Provides search_all() for parallel fan-out search across all third-party sources with round-robin result interleaving.

GenerationProvider — Abstract base class for text-to-3D model generation backends. Implements: generate, get_job_status, download_result. Concrete providers for Meshy (cloud AI), Tripo3D (cloud AI), Stability AI (synchronous cloud), Gemini Deep Think (AI-reasoned text/sketch-to-3D via Gemini + OpenSCAD), and OpenSCAD (local parametric). A GenerationRegistry auto-discovers providers from KILN_*_API_KEY environment variables.

Mesh Validation — Pipeline that checks generated STL/OBJ files for 3D-printing readiness: geometry parsing, manifold checks, dimension limits, polygon count validation. Uses pure Python (no external mesh libraries).

Job Queue — Priority queue backed by SQLite. Jobs are dispatched to idle printers by a background scheduler with history-based smart routing (best-performing printer for the job's file/material is preferred).

DeviceType — Enum classifying physical devices. Currently covers FDM printers with room for future device types.

DeviceAdapter — Alias for PrinterAdapter. Alternative import name.

Cross-Printer Learning — Agent-curated outcome database (print_outcomes table) that records success/failure/quality per printer and file. Safety-validated: rejects physically dangerous parameter values.

PaymentProvider — Abstract base class for payment processing backends. Implements: create_payment, get_payment_status, refund_payment, authorize_payment, capture_payment, cancel_payment. Concrete providers for Stripe and Circle (USDC).

PaymentManager — Orchestrates payment collection across providers. Routes to the correct rail (Stripe/Circle/crypto), enforces spend limits, persists transactions, and emits payment events.

HeaterWatchdog — Background daemon that monitors heater state and auto-cools idle heaters after a configurable timeout (default 30 min). Prevents heaters from being left on when no print is active.

LicenseManager — Offline-first license tier management. Resolves tier from key prefix (kiln_pro_, kiln_biz_, kiln_ent_) with cached remote validation fallback. Supports Free, Pro, Business, and Enterprise tiers. Enterprise unlocks RBAC, SSO (OIDC/SAML), audit trail export, lockable safety profiles, encrypted G-code at rest, per-printer overage billing, uptime SLA monitoring, and on-prem deployment. Never blocks printer operations.


Getting Started

Installation

# From PyPI
pip install kiln3d

# From source (development)
pip install -e ./kiln

Requirements: Python 3.10+, pip.

Discover Printers

kiln discover

Scans your local LAN (Ethernet or Wi-Fi) using mDNS and HTTP probing. If discovery does not find your printer, add it directly by IP with kiln auth.

Add a Printer

# OctoPrint
kiln auth --name ender3 --host http://octopi.local --type octoprint --api-key YOUR_KEY

# Moonraker
kiln auth --name voron --host http://voron.local:7125 --type moonraker

# Prusa Link
kiln auth --name prusa-mini --host http://192.168.1.44 --type prusaconnect --api-key YOUR_KEY

# Bambu Lab
kiln auth --name x1c --host 192.168.1.100 --type bambu --access-code 12345678 --serial 01P00A000000001

Ethernet-Only Setup (No Wi-Fi)

Kiln works the same over Ethernet and Wi-Fi because it talks to printer APIs over LAN IP.

# Verify endpoint from your host:
curl http://192.168.1.44/api/v1/status                  # Prusa Link
curl http://192.168.1.50:7125/server/info               # Moonraker
curl http://192.168.1.60/api/version                    # OctoPrint

# Register directly by IP (no discovery required):
kiln auth --name printer --host http://192.168.1.44 --type prusaconnect --api-key YOUR_KEY

First Print

kiln status                    # Verify printer is online
kiln preflight --material PLA  # Run safety checks
kiln upload benchy.gcode       # Upload file to printer
kiln print benchy.gcode        # Start printing
kiln wait                      # Block until complete

Slice and Print (STL to Object)

kiln slice benchy.stl --print-after

Auto-detects PrusaSlicer or OrcaSlicer, slices to G-code, uploads, and starts printing.


CLI Reference

Global Options

Flag Description
--printer NAME Target a specific printer (overrides active)
--json Output structured JSON (for agents/scripts)
--help Show command help

Commands

`kiln discover`

Scan the local LAN for printers via mDNS and HTTP probing. If no printers are found, use kiln auth --host <ip> to register directly.

`kiln auth`

Save printer credentials to ~/.kiln/config.yaml.

Flag Required Description
--name Yes Friendly name for this printer
--host Yes Printer URL (e.g., http://octopi.local)
--type Yes Backend: octoprint, moonraker, bambu, prusaconnect
--api-key OctoPrint, Prusa Link OctoPrint or Prusa Link API key
--access-code Bambu Bambu Lab access code
--serial Bambu Bambu Lab serial number

`kiln status`

Get printer state, temperatures, and active job progress.

`kiln files`

List G-code files available on the printer.

`kiln upload `

Upload a local G-code file to the printer.

`kiln print ... [--queue]`

Start printing. Accepts multiple files via glob expansion. With --queue, files are submitted to the job queue for sequential printing.

`kiln cancel`

Cancel the active print job.

`kiln pause` / `kiln resume`

Pause or resume the active print.

`kiln temp [--tool N] [--bed N]`

Get current temperatures, or set targets. Without flags, returns current temps.

`kiln gcode ...`

Send raw G-code commands to the printer. Commands are validated for safety before sending.

`kiln preflight [--material MAT]`

Run pre-print safety checks. Optional --material validates temperatures against expected ranges for: PLA, PETG, ABS, TPU, ASA, Nylon, PC.

`kiln slice [--print-after] [--profile PATH] [--output-dir DIR]`

Slice an STL/3MF/STEP/OBJ/AMF file to G-code. --print-after chains upload and print.

`kiln snapshot [--save PATH]`

Capture a webcam snapshot. --save writes to file; otherwise returns base64 in JSON mode.

`kiln wait [--timeout N] [--interval N]`

Block until the current print finishes. Returns exit code 0 on success, 1 on error/timeout.

`kiln history [--status S] [--limit N]`

Query past print records from the local database. Filter by completed, failed, cancelled.

`kiln printers`

List all saved printers with type and active status.

`kiln use `

Switch the active printer.

`kiln remove `

Remove a saved printer from config.

`kiln serve`

Start the MCP server (for agent integration).

`kiln cost [--material MAT] [--electricity-rate N] [--printer-wattage N]`

Estimate the cost of printing a G-code file. Analyzes extrusion, calculates filament weight and cost, and optionally includes electricity cost.

`kiln material set|show|spools|add-spool`

Material tracking commands. set records loaded material on a printer. show displays current material. spools lists spool inventory. add-spool registers a new spool.

`kiln level [--status] [--trigger] [--set-prints N] [--set-hours N] [--enable/--disable]`

Bed leveling management. Check status, manually trigger leveling, or configure auto-leveling policy.

`kiln stream [--port 8081] [--stop]`

Start or stop the MJPEG webcam streaming proxy. Proxies the upstream printer webcam stream to a local HTTP endpoint.

`kiln sync status|now|configure`

Cloud sync management. status shows sync state. now triggers immediate sync. configure sets cloud URL and API key.

`kiln plugins list|info`

Plugin management. list shows all discovered plugins. info shows details for a specific plugin.


MCP Server Reference

Installation

The MCP server starts via kiln serve or python -m kiln serve.

Claude Desktop Integration

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kiln": {
      "command": "python",
      "args": ["-m", "kiln", "serve"],
      "env": {
        "KILN_PRINTER_HOST": "http://octopi.local",
        "KILN_PRINTER_API_KEY": "your_key",
        "KILN_PRINTER_TYPE": "octoprint"
      }
    }
  }
}

Tool Catalog (Selected)

Kiln exposes 456 MCP tools in total. The most commonly used tools are documented below by category. Run kiln tools for the complete list.

Printer Control

Tool Input Output
printer_status Printer state, temps, job progress
start_print filename Confirmation or error
cancel_print Confirmation or error
pause_print Confirmation or error
resume_print Confirmation or error
set_temperature tool_temp, bed_temp Confirmation
send_gcode commands Response lines
validate_gcode commands Validation result
preflight_check filename, material Pass/fail with details

File Management

Tool Input Output
printer_files File list with sizes and dates
upload_file local_path Upload confirmation

Slicing

Tool Input Output
slice_model input_path, profile, output_dir G-code path, slicer info
find_slicer_tool Detected slicer path and version
slice_and_print input_path, profile Slice + upload + print result

Monitoring

Tool Input Output
printer_snapshot save_path Image bytes or base64
monitor_print printer_name, include_snapshot Standardized print status report (progress, temps, speed, camera, comments)
multi_copy_print model_path, copies, spacing_mm Arrange N copies on plate, slice, and print (PrusaSlicer --duplicate or STL fallback)

Fleet Management

Tool Input Output
fleet_status All printer states
register_printer name, type, host, ... Confirmation

Job Queue

Tool Input Output
submit_job filename, printer, priority, metadata Job ID (routes to best printer via historical success rate when printer is unspecified)
job_status job_id Job state and progress
queue_summary Queue overview
cancel_job job_id Confirmation

Model Discovery

Tool Input Output
search_all_models query, page, sources Interleaved results from all marketplaces
marketplace_info Connected sources, setup hints
search_models query, page Single-marketplace model list (Thingiverse — deprecated)
model_details thing_id Model metadata
model_files thing_id File list
download_model thing_id, file_id Local path
download_and_upload file_id, source, printer_name Download + upload in one step
browse_models sort, category Model list
list_model_categories Category list

System

Tool Input Output
kiln_health Version, uptime, module status
recent_events limit Event list
register_webhook url, events, secret Webhook ID
list_webhooks Webhook list
delete_webhook webhook_id Confirmation

Cost Estimation (Quick Reference)

See Cost Estimation below for the full tool set including slice_and_estimate, compare_print_options, and material cost from mesh geometry.

Tool Input Output
estimate_cost file_path, material, electricity_rate, printer_wattage Filament cost + electricity cost + total
list_materials 9 material profiles with densities and costs

Material Tracking

Tool Input Output
set_material printer_name, material, color, spool_id, tool_index Confirmation
get_material printer_name Loaded materials
check_material_match printer_name, expected_material Match result or warning
list_spools Spool inventory
add_spool material, color, brand, weight, cost Spool details
remove_spool spool_id Confirmation

Material Intelligence

Tool Input Output
get_material_properties material Full property sheet: thermal, mechanical, chemical, design limits
compare_materials material_a, material_b Side-by-side comparison across all properties
suggest_material requirements (strength, flexibility, heat_resistance, etc.) Ranked material recommendations with reasoning
build_material_overrides material, printer_model Slicer override dict for material+printer combination
reprint_with_material file_path, material, printer_name Re-slice and print with auto-generated material overrides
smart_reprint file_path, material, printer_name Find file, detect AMS slot, switch material, and print
multi_material_print objects (file_path + material pairs), printer_name Print multiple objects in different materials/colors on one plate

Bed Leveling

Tool Input Output
bed_level_status printer_name Leveling status and policy
trigger_bed_level printer_name Leveling result
set_leveling_policy printer_name, policy params Confirmation

Webcam Streaming

Tool Input Output
webcam_stream printer_name, action, port Stream status

Cloud Sync

Tool Input Output
cloud_sync_status Sync state
cloud_sync_now Sync results
cloud_sync_configure cloud_url, api_key, interval Confirmation

Plugins

Tool Input Output
list_plugins Plugin list
plugin_info name Plugin details

Billing & Payments

Tool Input Output
billing_status user_id Fee policy, monthly spend, payment methods, spend limits
billing_summary Aggregated billing summary
billing_history limit Recent billing charges with payment outcomes
billing_setup_url rail URL to link a payment method
billing_check_setup Polls pending Stripe SetupIntent; persists payment method on success
check_payment_status payment_id Non-blocking check of Circle/Stripe payment finality

External Provider Integrations *(As Integrations Launch)*

Kiln does not operate its own marketplace or manufacturing network. These tools integrate with third-party provider APIs for capacity discovery and job routing.

Tool Input Output
connect_provider_account name, location, capabilities, price_per_gram Connects local listing to provider integration account
sync_provider_capacity printer_id?, available? Syncs provider-side availability/capacity snapshot
list_provider_capacity Connected provider listings/capacity
find_provider_capacity material, location Available provider capacity by material/location
submit_provider_job file_url, material, printer_id Provider-managed remote job ID
provider_job_status job_id Provider job tracking details

Safety Audit

Tool Input Output
safety_audit Safety compliance report
get_session_log session_id? Full tool call history for an agent session (defaults to current session)
safety_settings Current safety/auto-print settings
safety_status Comprehensive safety status

Fulfillment Services (Third-Party Providers)

Routes manufacturing to third-party fulfillment providers (Craftcloud). Kiln acts as an API client to these providers — it does not operate manufacturing capacity or act as merchant of record.

Tool Input Output
fulfillment_materials provider Available materials from third-party print services
fulfillment_quote file_path, material_id, quantity, provider Manufacturing quote + provider ownership metadata (provider_name, provider_terms_url, support_owner=provider, merchant_of_record=provider)
fulfillment_order quote_id, shipping_option_id, payment_hold_id Order confirmation with billing + provider metadata (provider_order_id)
fulfillment_order_status order_id Order tracking details + provider ownership metadata
fulfillment_cancel order_id Cancellation confirmation
compare_print_options file_path, material Local vs. fulfillment cost comparison
fulfillment_compare_providers file_path, material_id, quantity Side-by-side quotes from all providers
fulfillment_filter_materials technology, color, finish, max_price_per_cm3 Filtered material catalog
fulfillment_batch_quote file_paths, material_id, quantities Per-item quotes with aggregated total
fulfillment_provider_health Health status of all fulfillment providers
fulfillment_order_history limit, provider Past orders for review or reorder
fulfillment_reorder order_id Past order details with reorder hints
fulfillment_insurance_options order_value Tiered shipping insurance options

Consumer Workflow (No Printer Required)

Tool Input Output
consumer_onboarding Step-by-step guide from idea to delivered product
validate_shipping_address street, city, country, state, postal_code Address validation with normalization
recommend_material use_case, budget, constraints Ranked material recommendations with reasoning
estimate_price technology, volume_cm3 or dimensions Instant price range (no API call)
estimate_timeline technology, quantity, country Order-to-delivery timeline with stage breakdown
supported_shipping_countries Supported shipping countries (23+ countries)

Model Generation

Supported providers: meshy, gemini, tripo3d, stability, openscad. Set KILN_GEMINI_API_KEY, KILN_MESHY_API_KEY, KILN_TRIPO3D_API_KEY, or KILN_STABILITY_API_KEY to enable cloud providers. For original idea-to-part creation, prefer generate_original_design, which chooses idea-to-CAD backends and explicitly does not treat raw openscad compilation as natural-language generation.

Tool Input Output
generate_model prompt, provider, format, style Generation job ID
generate_original_design requirements, provider, material, printer_model, max_attempts Best generated candidate plus readiness audit and retry history
generation_status job_id Job status and progress
download_generated_model job_id, output_dir Local file path with mesh validation
await_generation job_id, timeout, poll_interval Completed job result
generate_and_print prompt, provider, printer_name, profile Full pipeline: generate → validate → slice → print
validate_generated_mesh file_path Mesh validation report

Mesh Analysis & Repair

Pure-Python mesh operations — no external mesh libraries required. Operates directly on STL binary geometry for analysis, repair, transformation, and composition.

Tool Input Output
analyze_mesh_geometry file_path Volume, surface area, center of mass, overhangs, components, printability score (0-100)
repair_mesh file_path, output_path Degenerate triangle removal, normal recomputation, repair stats
repair_mesh_advanced file_path, output_path, close_holes Advanced repair: degenerate removal + boundary hole closing via fan triangulation
compose_models file_paths, output_path Merge multiple mesh files into one STL (no booleans — geometry concatenation)
export_model_3mf file_path, output_path Convert STL/OBJ/GLB to 3MF format (preferred by modern slicers)
optimize_print_orientation file_path, output_path Auto-rotate mesh to minimize overhangs and maximize bed contact
estimate_support_material file_path Support volume (mm³), weight (g), overhang triangle stats
compare_mesh_versions file_a, file_b Volume/surface area delta, Hausdorff distance, dimension changes, meshes_identical flag
predict_print_failure file_path, thresholds Risk score (0-100), verdict, per-failure details (thin walls, bridges, overhangs, top-heavy)
simplify_mesh_model file_path, target_ratio, output_path Vertex-clustering decimation — reduce triangle count while preserving shape
mesh_quality_scorecard file_path Multi-factor quality score: printability (35%), structural (25%), efficiency (20%), quality (20%). Letter grade A-F
estimate_material_cost file_path, material, infill_pct, wall_layers Filament weight (g), length (m), cost ($) for 9 materials
remove_mesh_floating_regions file_path, output_path, keep_largest Detect and remove disconnected geometry (fragments, support pillars)
check_print_readiness file_path, auto_fix, bed dimensions Single-call readiness gate: manifold, overhangs, build volume, degenerates. Optional auto-repair
mirror_mesh_model file_path, axis, output_path Mirror (reflect) mesh along X/Y/Z axis with correct winding order
hollow_mesh_model file_path, wall_thickness_mm, output_path Create hollow shell to save material, reports savings percentage
center_model_on_bed file_path, bed_x_mm, bed_y_mm, output_path Center mesh on build plate with z=0 grounding
analyze_non_manifold_edges file_path Edge classification: boundary (1 tri), manifold (2 tri), T-junction (3+). Watertight status
scale_mesh_to_fit file_path, max_x/y/z_mm, output_path Uniform scale to fit build volume while preserving aspect ratio
merge_mesh_files file_paths, output_path Combine multiple STL files into one (for multi-part assemblies)
split_mesh_by_component file_path, output_dir Split multi-body mesh into separate STL files per connected component
estimate_mesh_print_time file_path, layer_height, print_speed, material Geometry-based print time estimate (before slicing)
extract_model_from_3mf file_path, output_path Extract embedded mesh from .3mf or .gcode.3mf to STL (handles multi-object, Bambu files)
diagnose_mesh file_path Advanced defect analysis: self-intersections, normals, degenerate faces, floating fragments, holes

Parametric Design Templates

Tool Input Output
list_design_templates Available parametric templates (phone stand, hook, box, etc.)
generate_from_template template_id, parameters Generate model from template with custom parameters via OpenSCAD
generate_template_variations template_id, variation_count, parameter_ranges Batch-generate N variations across parameter space

Design Advisor & Iteration

Tool Input Output
design_advisor prompt, printer_model Recommend approach (template, OpenSCAD, or AI), material, and constraints
iterate_design prompt, provider, max_iterations, material Closed-loop: generate → validate → improve prompt → regenerate until passing
validate_openscad_code code Compile-check OpenSCAD code with structured error/warning output
estimate_print_time file_path, profile, slicer_path Slicer-based print time and filament estimate (requires slicer installed)
get_feedback_loop_status model_id Feedback loop iteration history and resolution status

Original Design Audit & Design DNA

The generate_original_design / audit_original_design pipeline produces idea-to-part designs and validates them through a multi-gate readiness audit. Each audit gate (mesh validity, printability, design constraints, orientation, build volume) independently passes or blocks with severity levels.

When designs are generated via OpenSCAD (parametric), the pipeline preserves the parametric source code alongside the compiled mesh. This "Design DNA" allows agents to iterate on the design by modifying parameters rather than regenerating from scratch. The audit_original_design function chains: mesh validation, printability analysis (7-dimension), design intelligence constraint checking, auto-orientation scoring, and prompt improvement feedback — returning a single OriginalDesignAudit with a readiness score, blockers list, and next-action recommendations.

Tool Input Output
generate_original_design requirements, provider, material, printer_model, max_attempts Best candidate + readiness audit + retry history
audit_original_design file_path, requirements, material, printer_model Multi-gate audit with readiness score, blockers, next actions
Tool Input Output
await_print_completion timeout_minutes, poll_interval Final print status
analyze_print_failure job_id Failure diagnosis with causes and recommendations
validate_print_quality job_id Quality assessment with snapshot and event analysis

Firmware Updates

Tool Input Output
firmware_status Component versions and update availability
update_firmware component Update result
rollback_firmware component Rollback result

Vision Monitoring (Agent-Delegated)

Kiln provides structured monitoring data (webcam snapshots, temperatures, print progress, phase context, failure hints) to agents. The agent's own vision model (Claude, GPT-4V, Gemini, etc.) analyzes the snapshots for defects — Kiln does not embed its own vision model. Kiln adds lightweight heuristic validation (brightness/variance checks) to detect blocked cameras or corrupted frames.

Tool Input Output
monitor_print_vision printer_name, include_snapshot, save_snapshot Snapshot + state + phase + failure hints for agent vision analysis
watch_print printer_name, snapshot_interval, max_snapshots, timeout, poll_interval Starts background watcher; returns watch_id immediately
watch_print_status watch_id Current progress, snapshots, outcome of background watcher
stop_watch_print watch_id Stops background watcher and returns final state

Cross-Printer Learning

Tool Input Output
record_print_outcome job_id, outcome, quality_grade, failure_mode, settings, notes Confirmation (safety-validated)
get_printer_insights printer_name, limit Success rate, failure breakdown, material stats, confidence
suggest_printer_for_job file_hash, material_type, file_name Ranked printers by success rate + availability
recommend_settings printer_name, material_type, file_hash Median temps/speed, mode slicer profile, confidence, quality distribution

Printability Engine

7-dimension analysis of STL/OBJ meshes for FDM printing readiness. Pure Python (no external mesh libraries). Each dimension produces a typed dataclass result; the composite report includes a 0-100 score, letter grade (A-F), and actionable recommendations.

Dimension What it measures Key output fields
Overhangs Triangles exceeding the max overhang angle (default 45 deg) max_overhang_angle, overhang_percentage, needs_supports, worst_regions
Thin walls Walls below nozzle diameter (default 0.4mm) min_wall_thickness_mm, thin_wall_count, problematic_regions
Bridging Unsupported horizontal spans max_bridge_length_mm, bridge_count, needs_supports_for_bridges
Bed adhesion Contact area at z-min as percentage of bounding-box footprint contact_area_mm2, contact_percentage, adhesion_risk (low/medium/high)
Support volume Estimated support material required estimated_support_volume_mm3, support_percentage, support_regions
Thermal stress Stress concentration from sharp cross-section changes and tall thin features stress_risk, concentration_zones, recommended_mitigations
Adhesion force Estimated peel/shear force at the bed interface for a given material and printer estimated_force_n, force_margin, detachment_risk

The last two dimensions (thermal stress and adhesion force) are material-aware heuristics. Thermal stress accounts for layer bonding weakness at sharp geometric transitions. Adhesion force estimation combines contact area, material shrinkage coefficients, and printer type (bed-slinger vs. CoreXY) to predict detachment risk.

Tool Input Output
analyze_printability file_path, nozzle_diameter, layer_height, max_overhang_angle, build_volume_* Full PrintabilityReport with score, grade, per-dimension results, recommendations
recommend_adhesion_settings file_path, material, printer_model, has_enclosure Brim/raft recommendation with slicer overrides dict
auto_orient_model file_path, output_path Auto-rotated mesh minimizing overhangs and maximizing bed contact
estimate_supports file_path Support volume and weight estimate

Adhesion intelligence includes a decision matrix combining contact percentage, material warp tendency (_HIGH_WARP_MATERIALS: ABS, ASA, PA, PC, etc.), bed-slinger detection, enclosure status, and model height to produce concrete slicer overrides (brim_width, brim_type, raft_layers).

Multi-Part Assembly & Job Splitting

Splits large models or multi-part assemblies across multiple printers for parallel printing. Three split modes: build volume overflow (model exceeds one printer), multi-copy distribution (N copies across fleet), and assembly splitting (multi-STL archive across printers with reassembly instructions).

Tool Input Output
plan_multi_copy_split file_path, copies, material SplitPlan with per-printer assignments, time savings percentage
plan_assembly_split file_paths, material SplitPlan with part-to-printer mapping and assembly instructions
split_plan_status plan_id SplitProgress with per-part status and estimated remaining time
cancel_split_plan plan_id Cancellation confirmation

Cost Estimation

G-code and 3MF cost analysis. Parses extrusion totals, calculates filament weight and cost from a 9-material database (PLA, PETG, ABS, TPU, ASA, Nylon, PC, PVA, HIPS), and optionally includes electricity cost from slicer-embedded time estimates. For 3MF files (including Bambu .gcode.3mf), extracts slicer metadata directly from the archive.

Tool Input Output
estimate_cost file_path, material, electricity_rate, printer_wattage Filament length/weight/cost, electricity cost, total cost, warnings
estimate_material_cost file_path, material, infill_pct, wall_layers Filament weight (g), length (m), cost ($) for mesh geometry
compare_print_options file_path, material Local vs. fulfillment provider cost comparison
slice_and_estimate input_path, material, printer_model Slice + cost + printability + adhesion recommendation (no print)
list_materials -- All material profiles with densities and costs

Pipelines (Runtime)

Tool Input Output
pipeline_status pipeline_id Current step, progress, elapsed time
pipeline_pause pipeline_id Confirmation (pauses at step boundary)
pipeline_resume pipeline_id Confirmation
pipeline_abort pipeline_id Confirmation with cleanup summary
pipeline_retry_step pipeline_id Retry result for the failed step

Model Cache

Tool Input Output
cache_model file_path, source, source_id, tags Cache entry with local path
search_cached_models query, source, tags Matching cached models
get_cached_model cache_id Model details and local path
list_cached_models limit, sort All cached models with metadata
delete_cached_model cache_id Confirmation

Database Management

Tool Input Output
backup_database output_dir Backup file path and size
verify_audit_integrity Integrity report (pass/fail, broken links)
clean_agent_memory max_age_days, dry_run Pruned entry count

Printer Trust

Tool Input Output
list_trusted_printers Trusted printers with fingerprints and verification status
trust_printer printer_name, fingerprint Trust confirmation
untrust_printer printer_name Removal confirmation

Design Intelligence

Constraint-aware design reasoning — agents query material properties, design patterns, and functional constraints before generating geometry.

Tool Input Output
get_design_brief requirements, material Complete design brief (materials, patterns, constraints, orientation)
get_material_design_profile material Full engineering properties for a printing material
list_design_materials All available materials with summary properties
recommend_design_material requirements, constraints Best material recommendation with reasoning
estimate_structural_load material, dimensions Safe structural load estimate for cantilevered sections
check_material_environment material, environment Material-environment compatibility check
get_printer_design_capabilities printer_id Design capability profile for a printer
list_printer_design_profiles All known printer design capability profiles
get_design_pattern_info pattern Detailed design rules for a functional pattern
list_design_patterns_catalog All available design patterns with descriptions
find_design_patterns use_case Design patterns that apply to a use case
match_design_requirements description Functional requirements that apply to a design task
validate_design_for_requirements design, requirements Validation against functional design requirements
troubleshoot_print_issue material, symptom Print problem diagnosis by material and symptom
check_printer_material_compatibility printer_id, material Printer-material compatibility check
get_post_processing_guide material Post-processing techniques for finishing a printed part
check_multi_material_pairing material_a, material_b Dual extrusion co-print compatibility check
get_print_diagnostic material, printer, symptom Comprehensive diagnostic combining multiple knowledge sources

Construction-Scale Design Intelligence

Tool Input Output
get_construction_design_brief requirements Design brief for construction-scale 3D printing
get_construction_material_profile material Engineering properties for a construction material
list_construction_materials_catalog All available construction printing materials
get_construction_pattern_info pattern Design rules for a construction printing pattern
list_construction_patterns_catalog All available construction printing patterns
get_construction_building_requirement requirement Detailed building program requirements
list_construction_building_requirements All building program requirement profiles
match_construction_building_requirements description Match a building description to known program requirements

Enterprise Features (Enterprise Tier)

Tool Input Output
export_audit_trail format (json/csv), start_date, end_date, tool, action, session_id Audit trail export (JSON or CSV)
lock_safety_profile profile_name Lock confirmation (prevents agent modifications)
unlock_safety_profile profile_name Unlock confirmation
manage_team_member email, role (admin/engineer/operator), action (add/remove/update) Team member status
printer_usage_summary Per-printer usage counts and overage billing details
uptime_report Rolling uptime metrics (1h/24h/7d/30d) with SLA compliance
encryption_status G-code encryption status and key configuration
report_printer_overage Printer overage billing breakdown (20 included, $15/mo each additional)
configure_sso provider_type (oidc/saml), IdP settings SSO configuration confirmation
sso_login_url provider_type Authorization URL for SSO login
sso_exchange_code code, state Session token
sso_status SSO configuration and provider connectivity status
rotate_encryption_key old_passphrase, new_passphrase, directory Key rotation results (rotated/skipped/failed counts)
database_status Database backend health (SQLite/PostgreSQL), connection info
list_fleet_sites All physical sites with printer counts
fleet_status_by_site Fleet status grouped by physical site
update_printer_site printer_name, site Site assignment confirmation
create_project project_id, name, client, budget_usd Project creation confirmation
log_project_cost project_id, category, amount, description Cost entry confirmation
project_cost_summary project_id Aggregate costs with category breakdown and budget tracking
client_cost_report client Cross-project cost aggregation for a client

MCP Resources

Read-only resources for agent context:

URI Description
kiln://status System-wide snapshot
kiln://printers Fleet listing
kiln://printers/{name} Single printer detail
kiln://queue Job queue summary
kiln://queue/{job_id} Single job detail
kiln://events Recent events (last 50)

Printer Adapters

OctoPrint

Communicates via HTTP REST. Requires an API key (generated in OctoPrint settings).

Configuration:

type: octoprint
host: http://octopi.local
api_key: YOUR_KEY

State Mapping: OctoPrint returns state as a set of boolean flags (printing, paused, error, ready, operational). The adapter maps flag combinations to PrinterStatus.

Webcam: Snapshots via GET /webcam/?action=snapshot.

Moonraker

Communicates via HTTP REST. No authentication required by default (Moonraker trusts local network).

Configuration:

type: moonraker
host: http://voron.local:7125

State Mapping: Moonraker returns Klipper state as a string (ready, printing, paused, error, shutdown). Direct mapping to PrinterStatus.

Webcam: Discovers cameras via GET /server/webcams/list, then fetches the snapshot URL.

Bambu Lab

Communicates via MQTT over LAN. Requires access code and serial number (found in printer settings).

Configuration:

type: bambu
host: 192.168.1.100
access_code: "12345678"
serial: "01P00A000000001"

Note: Requires paho-mqtt package. Kiln gracefully handles its absence.

Communicates via Prusa Link REST API (/api/v1/). Requires a Prusa Link API key.

Configuration:

type: prusaconnect
host: http://prusa-mk4.local
api_key: YOUR_KEY

State Mapping: Prusa Link returns state as a string (IDLE, PRINTING, PAUSED, FINISHED, ERROR, etc.). Direct mapping to PrinterStatus.

Limitations: No raw G-code or direct temperature control — these are managed through print files.

Elegoo (SDCP)

Communicates via the SDCP (Smart Device Control Protocol) over WebSocket on port 3030. No authentication required on local network. Covers Elegoo printers with cbd-tech/ChituBox mainboards: Centauri Carbon, Centauri Carbon 2, Saturn, Mars series.

Note: Elegoo Neptune 4 and OrangeStorm Giga run Klipper/Moonraker. Use the moonraker adapter type for those printers (port 4408 for Fluidd, 7125 for Moonraker API).

Configuration:

type: elegoo
host: 192.168.1.50
mainboard_id: ABCD1234ABCD1234  # optional, auto-discovered

Environment variables:

export KILN_PRINTER_HOST=192.168.1.50
export KILN_PRINTER_TYPE=elegoo
export KILN_PRINTER_MAINBOARD_ID=ABCD1234  # optional

State Mapping: SDCP returns numeric status codes. Mapping: 0=IDLE, 5/8/9/20=BUSY, 10=PAUSED, 13=PRINTING. Unknown codes default to UNKNOWN.

File Upload: SDCP uses a pull-based upload model — Kiln starts a temporary HTTP server, sends the printer a download URL, and the printer fetches the file. The printer must be able to reach the host machine on the ephemeral port.

Discovery: UDP broadcast of M99999 on port 3000. All SDCP printers on the network respond with their details.

Dependencies: Requires websocket-client package. Install with pip install 'kiln[elegoo]'.


Kiln provides a MarketplaceAdapter interface (mirroring the printer adapter pattern) for searching and downloading 3D models from third-party repositories. Kiln does not host or serve models itself — it searches external marketplaces on the user's behalf. A MarketplaceRegistry manages connected adapters and exposes search_all() for parallel fan-out across all sources.

Supported Marketplaces

Marketplace Protocol Auth Download Support Notes
MyMiniFactory HTTP REST v2 API key (?key=) Yes Primary marketplace — recommended for new integrations.
Cults3D GraphQL HTTP Basic No (metadata-only — provides URLs for manual download)
Thingiverse HTTP REST Bearer token Yes Deprecated — acquired by MyMiniFactory (Feb 2026). API may be sunset; prefer MyMiniFactory.

Configuration

Set environment variables for each marketplace you want to enable:

export KILN_MMF_API_KEY=your_key               # MyMiniFactory developer key (recommended)
export KILN_CULTS3D_USERNAME=your_username      # Cults3D account username
export KILN_CULTS3D_API_KEY=your_key            # https://cults3d.com/en/api/keys
export KILN_THINGIVERSE_TOKEN=your_token        # Deprecated — Thingiverse acquired by MyMiniFactory (Feb 2026)

Adapters are auto-registered at server startup based on available credentials. Only configured marketplaces participate in searches.

search_all_models fans out the query to all connected marketplaces in parallel using a thread pool. Results are interleaved round-robin across sources for variety. If one marketplace fails (rate limit, timeout), results from the others still return.

Each result includes a source field identifying the marketplace, plus print-readiness hints:

  • is_free — whether the model is free to download
  • has_sliceable_files — has STL/3MF/OBJ files that need slicing
  • has_printable_files — has ready-to-print G-code

Download and Upload

download_and_upload combines marketplace file download with printer upload in a single tool call. Accepts a source parameter to target any marketplace that supports downloads. Cults3D is excluded (metadata-only).


Safety Systems

Pre-flight Checks

Every print job should pass through preflight_check():

  1. Printer online — Adapter can reach the printer
  2. Printer idle — No active job running
  3. File exists — Target file is on the printer
  4. Temperature safe — Targets within safe bounds
  5. Material validation — When --material specified, temperatures match expected ranges

G-code Validation

The validate_gcode() function screens commands before they reach hardware:

  • Blocked: Firmware reset, EEPROM wipe, unsafe axis movements
  • Warned: High temperatures, rapid moves without homing
  • Passed: Standard print commands, temperature sets within limits

Temperature Limits

Limit Value
Hotend maximum 300C
Bed maximum 130C
PLA range (tool) 180-220C
PETG range (tool) 220-260C
ABS range (tool) 230-270C

Authentication

Disabled by default. Enable for multi-user or network-exposed setups.

export KILN_AUTH_ENABLED=1
export KILN_AUTH_KEY=your_secret_key

Scopes: read, write, admin.

Read-only tools (printer_status, printer_files, fleet_status) never require authentication.


Webhooks

Register HTTP endpoints for real-time event notifications:

register_webhook(url="https://example.com/hook", events=["job.completed", "print.failed"])

Event types: job.submitted, job.dispatched, job.completed, job.failed, job.cancelled, print.started, print.paused, print.resumed, print.failed, printer.online, printer.offline, printer.error, stream.started, stream.stopped, sync.completed, sync.failed, leveling.triggered, leveling.completed, leveling.failed, leveling.needed, material.loaded, material.mismatch, material.spool_low, material.spool_empty, plugin.loaded, plugin.error, vision.check, vision.alert.

Payloads are signed with HMAC-SHA256 when a secret is provided.


Configuration

Config File

Location: ~/.kiln/config.yaml

active_printer: my-voron

printers:
  my-voron:
    type: moonraker
    host: http://voron.local:7125

  ender3:
    type: octoprint
    host: http://octopi.local
    api_key: ABC123

  x1c:
    type: bambu
    host: 192.168.1.100
    access_code: "12345678"
    serial: "01P00A000000001"

settings:
  timeout: 30
  retries: 3

Environment Variables

Variable Description
KILN_PRINTER_HOST Printer URL (fallback when no config)
KILN_PRINTER_API_KEY API key for OctoPrint
KILN_PRINTER_TYPE Backend type
KILN_SLICER_PATH Explicit path to slicer binary
KILN_MMF_API_KEY MyMiniFactory API key
KILN_CULTS3D_USERNAME Cults3D account username
KILN_CULTS3D_API_KEY Cults3D API key
KILN_THINGIVERSE_TOKEN Thingiverse API token (deprecated — acquired by MyMiniFactory, Feb 2026)
KILN_AUTH_ENABLED Enable API key auth (1/0)
KILN_AUTH_KEY Secret key for auth
KILN_ENCRYPTION_KEY Encryption key for G-code at rest (Enterprise)
KILN_SSO_PROVIDER SSO provider type: oidc or saml (Enterprise)
KILN_SSO_ISSUER OIDC issuer URL or SAML IdP metadata URL (Enterprise)
KILN_SSO_CLIENT_ID OIDC client ID (Enterprise)
KILN_SSO_CLIENT_SECRET OIDC client secret (Enterprise)

Precedence

CLI flags > Environment variables > Config file.


Development

Setup

git clone https://github.com/codeofaxel/Kiln.git
cd kiln
pip install -e "./kiln[dev]"
pip install -e "./octoprint-cli[dev]"

Running Tests

cd kiln && python3 -m pytest tests/ -v    # 8,000+ tests
cd ../octoprint-cli && python3 -m pytest tests/ -v  # 239 tests

Adding a New Printer Adapter

  1. Create kiln/src/kiln/printers/yourbackend.py
  2. Implement all abstract methods from PrinterAdapter in base.py
  3. Return typed dataclasses — never raw dicts
  4. Map all backend states to PrinterStatus enum
  5. Handle connection failures gracefully (return OFFLINE)
  6. Add to the adapter factory in cli/config.py
  7. Write tests following the pattern in tests/test_server.py

Project Structure

kiln/src/kiln/
    __init__.py
    __main__.py          # Entry point
    server.py            # MCP server + all tools
    slicer.py            # PrusaSlicer/OrcaSlicer integration
    registry.py          # Fleet printer registry
    queue.py             # Priority job queue
    scheduler.py         # Background job dispatcher with smart routing
    events.py            # Pub/sub event bus
    persistence.py       # SQLite storage
    webhooks.py          # Webhook delivery
    auth.py              # API key authentication
    billing.py           # Fee tracking
    gcode.py             # G-code safety validator (per-printer limits)
    safety_profiles.py   # Bundled safety database (29 printer models)
    slicer_profiles.py   # Bundled slicer profiles (auto .ini generation)
    printer_intelligence.py  # Printer knowledge base (quirks, materials, fixes)
    design_intelligence.py   # Design knowledge queries (materials, patterns, constraints)
    design_validator.py      # Design validation + feedback bridge
    pipelines.py         # Pre-validated print pipelines (quick_print, calibrate, benchmark)
    cost_estimator.py    # Print cost estimation (G-code + 3MF, 9 materials)
    printability.py      # 7-dimension printability engine (overhangs, thin walls, bridging, adhesion, supports, thermal stress, adhesion force)
    job_splitter.py      # Multi-printer job splitting (multi-copy, assembly, build volume overflow)
    original_design.py   # Original design audit pipeline (multi-gate readiness)
    materials.py         # Multi-material tracking
    bed_leveling.py      # Bed leveling trigger system
    streaming.py         # MJPEG webcam proxy
    cloud_sync.py        # Cloud sync manager
    heater_watchdog.py   # Auto-cooldown watchdog for idle heaters
    licensing.py         # License tier management (Free/Pro/Business/Enterprise)
    sso.py               # SSO authentication (OIDC/SAML, IdP role mapping, email domain allowlists)
    gcode_encryption.py  # G-code encryption at rest (Fernet/PBKDF2)
    printer_billing.py   # Per-printer overage billing (metered via Stripe)
    teams.py             # Team seat management with RBAC (admin/engineer/operator)
    uptime.py            # Rolling uptime health monitoring (1h/24h/7d/30d, 99.9% SLA)
    project_costs.py     # Per-project cost tracking for manufacturing bureaus
    model_metadata.py    # Model metadata management
    wallets.py           # Crypto wallet configuration (Solana/Ethereum donations)
    plugins.py           # Plugin system
    backup.py            # Database backup and restore
    log_config.py        # Structured logging configuration
    model_cache.py       # Local model cache with metadata tracking
    plugins/             # Auto-discovered MCP tool plugins (22 modules)
        printability_tools.py    # Printability analysis, auto-orient, adhesion
        recovery_tools.py        # Job splitting, print recovery, checkpoint
        estimate_tools.py        # Slice-and-estimate (no-print cost preview)
        smart_print_tools.py     # Smart reprint, AMS-aware printing
        design_tools.py          # Design intelligence MCP tools
        generation_tools.py      # Model generation + original design
        fulfillment_tools.py     # Third-party fulfillment provider tools
        mesh_diagnostic_tools.py # Advanced mesh diagnostics
        ...                      # + 14 more plugin modules
    payments/
        base.py          # PaymentProvider interface, PaymentRail enum
        manager.py       # Payment orchestration across providers
        stripe_provider.py   # Stripe payment provider
        circle_provider.py   # Circle USDC payment provider
    gateway/
        network.py       # Provider-integration gateway client (canonical partner_* tools + legacy network_* aliases)
    data/
        safety_profiles.json     # Per-printer safety limits (temps, feedrates, flow)
        slicer_profiles.json     # Per-printer slicer settings (INI key-values)
        printer_intelligence.json  # Firmware quirks, materials, failure modes
        design_knowledge/          # Design intelligence data files
            material_troubleshooting.json   # 20 materials × 5-7 failure modes each
            printer_material_compatibility.json  # 29 printers × 20 materials
            multi_material_pairing.json     # Soluble support pairs, co-print matrix
            post_processing.json            # Finishing techniques per material
    printers/
        base.py          # Abstract PrinterAdapter + dataclasses
        octoprint.py     # OctoPrint REST adapter
        moonraker.py     # Moonraker REST adapter
        bambu.py         # Bambu Lab MQTT adapter
        prusaconnect.py  # Prusa Link adapter
        elegoo.py        # Elegoo SDCP adapter (WebSocket)
    fulfillment/
        base.py          # Fulfillment adapter interface
        registry.py      # Provider registry and factory
        craftcloud.py    # Craftcloud v5 API client (third-party; upload → price → cart → order)
        sculpteo.py      # Sculpteo partner API client (third-party; inactive — pending partner credentials)
    marketplaces/
        base.py          # Marketplace adapter interface
        myminifactory.py # MyMiniFactory API client (primary)
        cults3d.py       # Cults3D API client
        thingiverse.py   # Thingiverse API client (deprecated — acquired by MMF)
    cli/
        main.py          # Click CLI entry point
        config.py        # Config management
        discovery.py     # mDNS printer scanning
        output.py        # JSON/text formatting

deploy/                  # On-prem Enterprise deployment
    k8s/                 # Kubernetes manifests (9 files: namespace, deployment, service, ingress, configmap, secrets, PVC, network policies, HPA)
    helm/kiln/           # Helm chart (12 files: Chart.yaml, values.yaml, templates/)

Kiln is a project of Hadron Labs Inc.