This project grew out of Subthiel, my own company for 3D printing & software development.
--- ## ๐ What is this? This MCP server bridges the gap between AI assistants (like Claude) and your self-hosted [Spoolman](https://github.com/Donkie/Spoolman) instance. Instead of clicking through the Spoolman UI, you can simply **ask** your AI assistant: > _"How much PLA do I have left?"_ > _"Add a new Bambu Lab PETG spool, 1kg, red."_ > _"Mark spool #12 as used by 50g."_ The server exposes the **full Spoolman REST API v1** as MCP tools โ every vendor, filament, spool, setting, custom field, lookup, and export endpoint is covered. --- ## โจ Features - ๐ญ **Vendor Management** โ Create, read, update, delete vendors - ๐จ **Filament Management** โ Full CRUD with color, temperature settings, article numbers - ๐งต **Spool Management** โ Track spools, log usage (by weight or length), weight measurement, archiving - โ๏ธ **Settings** โ Read and write Spoolman configuration - ๐ท๏ธ **Custom Fields** โ Manage extra fields for vendors, filaments, and spools - ๐ **Lookups** โ Browse all materials, locations, lot numbers, article numbers - ๐ฆ **Export** โ Export data as JSON or CSV - ๐ **System** โ Health check, info, and backup trigger > [!NOTE] > This server communicates with your **local/self-hosted** Spoolman instance. You need a running Spoolman before using this MCP server. --- ## ๐ Requirements | Requirement | Version | |---|---| | Node.js | โฅ 18 | | npm | โฅ 9 | | Spoolman | Any recent version | | Claude Desktop / Claude Code | Any | --- ## โก Quick Start ### 1. Clone & Install ```bash git clone https://github.com/Disane87/spoolman-mcp.git cd spoolman-mcp npm install npm run build ``` ### 2. Configure Claude Desktop Add the following to your `claude_desktop_config.json`: **macOS / Linux:** `~/.config/claude/claude_desktop_config.json` **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "spoolman": { "command": "node", "args": ["/absolute/path/to/spoolman-mcp/dist/index.js"], "env": { "SPOOLMAN_URL": "http://localhost:7912" } } } } ``` > [!IMPORTANT] > Replace `/absolute/path/to/spoolman-mcp` with the actual path where you cloned the repository, and `http://localhost:7912` with the URL of your Spoolman instance. ### 3. Restart Claude Desktop & Start Chatting! ๐ --- ## ๐ง Configuration The server is configured via **environment variables**: | Variable | Required | Description | Example | |---|---|---|---| | `SPOOLMAN_URL` | โ Yes | Base URL of your Spoolman instance | `http://localhost:7912` | | `SPOOLMAN_API_KEY` | โ No | Bearer token (if behind a proxy with auth) | `my-secret-key` | --- ## ๐ ๏ธ Available MCP Tools ### ๐ญ Vendors | Tool | Description | |---|---| | `spoolman_list_vendors` | Search and list all vendors | | `spoolman_get_vendor` | Get a single vendor by ID | | `spoolman_create_vendor` | Create a new vendor | | `spoolman_update_vendor` | Update an existing vendor | | `spoolman_delete_vendor` | Delete a vendor (cascades to filaments!) | ### ๐จ Filaments | Tool | Description | |---|---| | `spoolman_list_filaments` | Search filaments by name, material, color, vendor... | | `spoolman_get_filament` | Get a single filament by ID | | `spoolman_create_filament` | Create a new filament definition | | `spoolman_update_filament` | Update an existing filament | | `spoolman_delete_filament` | Delete a filament | ### ๐งต Spools | Tool | Description | |---|---| | `spoolman_list_spools` | Search spools with extensive filters | | `spoolman_get_spool` | Get a single spool by ID | | `spoolman_create_spool` | Register a new spool | | `spoolman_update_spool` | Update spool metadata | | `spoolman_delete_spool` | Delete a spool | | `spoolman_use_spool` | Log filament consumption (g or mm) | | `spoolman_measure_spool` | Update remaining weight via scale measurement | ### โ๏ธ Settings | Tool | Description | |---|---| | `spoolman_get_all_settings` | Get all Spoolman settings | | `spoolman_get_setting` | Get a specific setting by key | | `spoolman_set_setting` | Change a setting value | ### ๐ท๏ธ Custom Fields | Tool | Description | |---|---| | `spoolman_list_fields` | List custom fields for an entity type | | `spoolman_upsert_field` | Add or update a custom field | | `spoolman_delete_field` | Remove a custom field | ### ๐ Lookups | Tool | Description | |---|---| | `spoolman_list_materials` | List all known material types | | `spoolman_list_locations` | List all storage locations | | `spoolman_list_lot_numbers` | List all lot/batch numbers | | `spoolman_list_article_numbers` | List all article numbers | | `spoolman_rename_location` | Rename a storage location | ### ๐ฆ Export | Tool | Description | |---|---| | `spoolman_export_spools` | Export all spools as JSON or CSV | | `spoolman_export_filaments` | Export all filaments as JSON or CSV | | `spoolman_export_vendors` | Export all vendors as JSON or CSV | ### ๐ System | Tool | Description | |---|---| | `spoolman_get_info` | Get Spoolman version and config info | | `spoolman_health_check` | Check if Spoolman is reachable | | `spoolman_trigger_backup` | Trigger a database backup (SQLite only) | --- ## ๐ฌ Example Conversations Once connected, you can have natural conversations like: ``` You: How many spools do I currently have? Claude: You have 14 spools in Spoolman. 3 of them are archived. The active spools include 5x PLA, 4x PETG, and 2x ABS. ``` ``` You: Add a new Bambu Lab PLA Basic spool. It's red, 1kg, 1.75mm. Claude: I'll create that for you right away! โ Spool created: Bambu Lab PLA Basic (Red) โ 1000g remaining. ``` ``` You: I just printed something and used about 45g from spool #7. Claude: Done! Spool #7 now has 623g remaining (was 668g). ``` ``` You: I just weighed spool #3 on my kitchen scale โ it's 312g total. Claude: Got it! Based on the empty spool weight of 190g, spool #3 now shows 122g of filament remaining. ``` --- ## ๐๏ธ Project Structure ``` spoolman-mcp/ โโโ src/ โ โโโ index.ts # MCP server entry point & transport โ โโโ client.ts # Typed Spoolman REST API client โ โโโ tools/ โ โโโ system.ts # System tools (health, info, backup) โ โโโ vendors.ts # Vendor CRUD tools โ โโโ filaments.ts # Filament CRUD tools โ โโโ spools.ts # Spool management tools โ โโโ settings.ts # Settings tools โ โโโ fields.ts # Custom field tools โ โโโ lookup.ts # Lookup / discovery tools โ โโโ export.ts # Data export tools โโโ dist/ # Compiled JavaScript (after npm run build) โโโ package.json โโโ tsconfig.json โโโ README.md ``` --- ## ๐จ Development ```bash # Install dependencies npm install # Build TypeScript npm run build # Watch mode (auto-rebuild on changes) npm run watch # Run directly with ts-node (no build step) SPOOLMAN_URL=http://localhost:7912 npm run dev ``` --- ## ๐ค Contributing Contributions are welcome! Feel free to open an issue or pull request if you find a bug, have a feature idea, or want to improve the documentation. 1. Fork the repository 2. Create a feature branch (`git checkout -b feat/my-feature`) 3. Commit your changes (`git commit -m 'feat: add my feature'`) 4. Push to the branch (`git push origin feat/my-feature`) 5. Open a Pull Request --- ## ๐ License MIT License โ see [LICENSE](./LICENSE) for details. --- ## ๐ Related Spoolman Projects Check out these other projects from the Spoolman ecosystem: | Project | Description | |---------|-------------| | [๐ Spoolman Home Assistant](https://github.com/Disane87/spoolman-homeassistant) | Integrate Spoolman with Home Assistant โ track spools, get notifications, automate your printing workflow | | [๐จ Spoolman Filament Swatch](https://github.com/Disane87/spoolman-filament-swatch) | Beautiful, interactive filament color browser for Spoolman. [Live Demo](https://spoolswatch.disane.dev/) | | [๐ฆ Spoolman Filament Extractor](https://github.com/Disane87/Spoolman-filament-extractor) | Extract your filaments from Spoolman to SpoolmanDB format | | [๐๏ธ SpoolmanDB](https://github.com/Donkie/SpoolmanDB) | Centralized community filament database used by Spoolman | | [๐จ๏ธ Spoolman](https://github.com/Donkie/Spoolman/) | The awesome filament manager that powers everything | --- ## ๐ Credits - [Spoolman](https://github.com/Donkie/Spoolman) by [@Donkie](https://github.com/Donkie) โ the awesome filament management system that makes this possible - [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic โ the open standard powering AI tool integration - Inspired by [spoolman-homeassistant](https://github.com/Disane87/spoolman-homeassistant) ๐ ---Made with โค๏ธ for the 3D printing community
Made by me at Subthiel โ my company for 3D printing & software development