Skip to main content
Glama
filament

filament

by fdaira
README.md
# 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)

```bash
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) |

## Deploy to a Linux server (systemd)

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

```bash
./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.

```bash
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

```bash
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:

```bash
python3 tools/build_catalog.py
```

Sources (names, hex codes and SKUs only):

- **Bambu Lab** — `filaments_color_codes.json` from [Bambu Studio](https://github.com/bambulab/BambuStudio)
- **Snapmaker, Sunlu, Polymaker** — the public product listings of their US online stores
- **Hex codes** for Snapmaker, Sunlu and Polymaker — [SpoolmanDB](https://github.com/Donkie/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](LICENSE)