Skip to main content
Glama
filament

filament

by fdaira

Filament Inventory

A self-hosted inventory for 3D-printer filament: a small web app for your phone or desktop, plus an MCP server so Claude (or any MCP client) can read and update the same inventory.

  • Load filament — brand, type, color, quantity, weight, location. Type or scan the SKU printed on the spool and everything fills itself in.

  • Find & unload — search by brand, type, color, SKU, location or printer; move a spool onto a named printer and return it to stock with the grams left.

  • Color catalog — official color names, hex swatches and SKUs for Bambu Lab, Snapmaker, Sunlu and Polymaker (about 1,660 colors and over 2,000 SKUs, including refills and 2.85 mm variants).

  • Claude integration — ask "how much black PLA do I have?", "put the blue Polymaker on the X1C", or "add a spool of CA04076".

One Python process serves everything: the web UI at /, a JSON API at /api/* and the MCP endpoint at /mcp. Data lives in a single SQLite file.

Quick start (local)

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
FILAMENT_TOKEN=choose-a-secret .venv/bin/python filament_server.py --http

Open http://localhost:8765/ and enter the token. Without --http the server speaks MCP over stdio instead (for local MCP clients).

Variable

Default

Meaning

FILAMENT_DB

~/.local/share/filament-inventory/filament.db

SQLite database file

FILAMENT_HOST

0.0.0.0

HTTP bind address

FILAMENT_PORT

8765

HTTP port

FILAMENT_TOKEN

(unset)

Bearer token required for /api and /mcp (strongly recommended)

Related MCP server: MCP 3D Printer Server

Deploy to a Linux server (systemd)

From your computer, with SSH access and sudo on the server:

./deploy/deploy.sh myserver

This copies the app to /opt/filament-mcp, creates a filament-mcp system user and a hardened systemd service, stores the database in /var/lib/filament-mcp/ (backed up on every deploy), and generates an access token in /etc/filament-mcp.env (root-only). Re-running it upgrades the code and keeps your data and token.

ssh myserver sudo grep FILAMENT_TOKEN /etc/filament-mcp.env   # show the token
./deploy/fetch-token.sh myserver                              # or copy it to ~/.config/filament-mcp/token

Logs: journalctl -u filament-mcp -f.

Connect Claude Code

claude mcp add --transport http --scope user filament http://myserver:8765/mcp --header "Authorization: Bearer <TOKEN>"

MCP tools

Tool

What it does

add_spool

Add spool(s): material, color, brand, weight, location, SKU, count

list_spools

Search, filter by brand/type/color, in stock vs on a printer, low stock

get_spool

One spool with usage and printer history

use_filament

Deduct grams after a print

unload_spool / return_spool

Put a spool on a printer / back into stock

update_spool / remove_spool

Edit or delete a spool

inventory_summary

Spools and grams per material, color, or brand

catalog_colors

Look up catalog colors by brand, type, name or SKU

Color catalog

catalog.json is generated by tools/build_catalog.py; re-run it to pick up new colors:

python3 tools/build_catalog.py

Sources (names, hex codes and SKUs only):

  • Bambu Lab — filaments_color_codes.json from Bambu Studio

  • Snapmaker, Sunlu, Polymaker — the public product listings of their US online stores

  • Hex codes for Snapmaker, Sunlu and Polymaker — SpoolmanDB (MIT License, Copyright (c) Daniel Hultgren)

Brand names and trademarks belong to their owners; this project is not affiliated with them. Store data can be incomplete or change at any time — some colors have no SKU or no hex code.

Security

The HTTP endpoint is plain HTTP protected by a bearer token, which suits a home network. Don't expose port 8765 to the internet; put it behind a TLS reverse proxy or a VPN such as Tailscale if you need remote access.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables interaction with 3D printer management systems through an MCP server, supporting STL file manipulation, slicing, and control of printers like OctoPrint, Klipper, Duet, and more.
      30
      3,386 npm
      268
      GPL 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables users to connect Claude with various 3D printer management systems, allowing tasks like printer status monitoring, file management, print job control, and STL file manipulation.
      3,386 npm
      GPL 2.0
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to manage 3D printer filament inventory through Spoolman's API, allowing natural language queries and commands for CRUD operations on vendors, filaments, spools, settings, and more.
      34
      12 npm
      21
      MIT
    • A
      license
      A
      quality
      F
      maintenance
      Enables AI assistants to manage 3D printing inventory, filament spools, printers, projects, and print trackers through a self-hosted Print Vault instance.
      40
      AGPL 3.0