🧵 Spoolman MCP Server

A Model Context Protocol server for Spoolman — manage your entire 3D printer filament inventory through natural language with Claude and other AI assistants! 🎉

---

🚀 What is this?

This MCP server bridges the gap between AI assistants (like Claude) and your self-hosted 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

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

{
  "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

# 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 for details.

---

🔗 Related Spoolman Projects

Check out these other projects from the Spoolman ecosystem:

| Project | Description | |---------|-------------| | 🏠 Spoolman Home Assistant | Integrate Spoolman with Home Assistant — track spools, get notifications, automate your printing workflow | | 🎨 Spoolman Filament Swatch | Beautiful, interactive filament color browser for Spoolman. Live Demo | | 📦 Spoolman Filament Extractor | Extract your filaments from Spoolman to SpoolmanDB format | | 🗄️ SpoolmanDB | Centralized community filament database used by Spoolman | | 🖨️ Spoolman | The awesome filament manager that powers everything |

---

🙏 Credits

• Spoolman by @Donkie — the awesome filament management system that makes this possible
• Model Context Protocol by Anthropic — the open standard powering AI tool integration
• Inspired by spoolman-homeassistant 💙

---

<p align="center">Made with ❤️ for the 3D printing community</p>