Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@spoolman-mcp How much PLA do I have left?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for Spoolman — manage your entire 3D printer filament inventory through natural language with Claude and other AI assistants! 🎉
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.
Related MCP server: StashDog MCP Server
🏭 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
This server communicates with yourlocal/self-hosted Spoolman instance. You need a running Spoolman before using this MCP server.
Requirement | Version |
Node.js | ≥ 18 |
npm | ≥ 9 |
Spoolman | Any recent version |
Claude Desktop / Claude Code | Any |
git clone https://github.com/Disane87/spoolman-mcp.git
cd spoolman-mcp
npm install
npm run buildAdd 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"
}
}
}
}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.
The server is configured via environment variables:
Variable | Required | Description | Example |
| ✅ Yes | Base URL of your Spoolman instance |
|
| ❌ No | Bearer token (if behind a proxy with auth) |
|
Tool | Description |
| Search and list all vendors |
| Get a single vendor by ID |
| Create a new vendor |
| Update an existing vendor |
| Delete a vendor (cascades to filaments!) |
Tool | Description |
| Search filaments by name, material, color, vendor... |
| Get a single filament by ID |
| Create a new filament definition |
| Update an existing filament |
| Delete a filament |
Tool | Description |
| Search spools with extensive filters |
| Get a single spool by ID |
| Register a new spool |
| Update spool metadata |
| Delete a spool |
| Log filament consumption (g or mm) |
| Update remaining weight via scale measurement |
Tool | Description |
| Get all Spoolman settings |
| Get a specific setting by key |
| Change a setting value |
Tool | Description |
| List custom fields for an entity type |
| Add or update a custom field |
| Remove a custom field |
Tool | Description |
| List all known material types |
| List all storage locations |
| List all lot/batch numbers |
| List all article numbers |
| Rename a storage location |
Tool | Description |
| Export all spools as JSON or CSV |
| Export all filaments as JSON or CSV |
| Export all vendors as JSON or CSV |
Tool | Description |
| Get Spoolman version and config info |
| Check if Spoolman is reachable |
| Trigger a database backup (SQLite only) |
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.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# 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 devContributions 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.
Fork the repository
Create a feature branch (git checkout -b feat/my-feature)
Commit your changes (git commit -m 'feat: add my feature')
Push to the branch (git push origin feat/my-feature)
Open a Pull Request
MIT License — see LICENSE for details.
Check out these other projects from the Spoolman ecosystem:
Project | Description |
Integrate Spoolman with Home Assistant — track spools, get notifications, automate your printing workflow | |
Beautiful, interactive filament color browser for Spoolman. Live Demo | |
Extract your filaments from Spoolman to SpoolmanDB format | |
Centralized community filament database used by Spoolman | |
The awesome filament manager that powers everything |
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 💙
Create a new filament definition in Spoolman. Density and diameter are required.
Inputs: density (required), diameter (required), name, price, +11 more.
Create a new spool in Spoolman. A filament_id is required. Specify either remaining_weight or used_weight (not both).
Inputs: filament_id (required), lot_nr, comment, archived, +7 more.
Create a new vendor in Spoolman.
Inputs: name (required), comment.
Remove a custom extra field from an entity type.
Inputs: key (required), entity_type (required).
Delete a filament by ID.
Inputs: id (required).
Delete a spool by ID.
Inputs: id (required).
Delete a vendor by ID. This will cascade to associated filaments.
Inputs: id (required).
Export all filaments from Spoolman as JSON or CSV.
Inputs: format.
Export all spools from Spoolman as JSON or CSV.
Inputs: format.
Export all vendors from Spoolman as JSON or CSV.
Inputs: format.
Retrieve all Spoolman configuration settings.
Inputs: no named parameters.
Get a single filament by its ID.
Inputs: id (required).
Get general Spoolman API information (version, database type, debug mode, paths).
Inputs: no named parameters.
Retrieve a single Spoolman configuration setting by key.
Inputs: key (required).
Get a single spool by its ID, including remaining weight and usage stats.
Inputs: id (required).
Get a single vendor by its ID.
Inputs: id (required).
Check whether the Spoolman instance is healthy and reachable.
Inputs: no named parameters.
List all article numbers of filaments currently tracked in Spoolman.
Inputs: no named parameters.
List all custom extra fields defined for a given entity type (vendor, filament, or spool).
Inputs: entity_type (required).
List and search filaments in Spoolman. Supports filtering by vendor, material, color, article number and more.
Inputs: name, sort, limit, offset, +6 more.
List all spool storage locations defined in Spoolman.
Inputs: no named parameters.
List all lot/batch numbers of spools currently tracked in Spoolman.
Inputs: no named parameters.
List all filament material types that exist in Spoolman (e.g. PLA, PETG, ABS).
Inputs: no named parameters.
List and search spools in Spoolman. Filter by filament, vendor, material, location, lot number and more.
Inputs: sort, limit, lot_nr, offset, +7 more.
List and search vendors in Spoolman. Supports filtering by name and pagination.
Inputs: name, sort, limit, offset.
Update a spool's remaining filament by providing a current weight measurement (spool + filament together in grams).
Inputs: id (required), weight (required).
Rename an existing spool storage location. All spools at the old location will be updated to the new name.
Inputs: location (required), new_name (required).
Set a Spoolman configuration value by key.
Inputs: key (required), value.
Trigger a database backup on the Spoolman instance (SQLite only). Returns the backup file path.
Inputs: no named parameters.
Update an existing filament by ID. Only provide the fields you want to change.
Inputs: id (required), name, price, weight, +10 more.
Update an existing spool by ID. Only provide the fields you want to change. remaining_weight and used_weight are mutually exclusive.
Inputs: id (required), lot_nr, comment, archived, +6 more.
Update an existing vendor by ID. Only provide the fields you want to change.
Inputs: id (required), name, comment.
Add or update a custom extra field for a given entity type.
Inputs: key (required), order (required), field_type (required), entity_type (required), +4 more.
Log filament consumption for a spool. Provide either use_length (mm) or use_weight (g), not both.
Inputs: id (required), use_length, use_weight.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 34 tools
Most tools have clear, distinct purposes (e.g., list_filaments vs list_materials vs list_article_numbers). Some potential confusion exists between use_spool and measure_spool, or get_info and health_check, but descriptions clarify these differences.
Tools generally follow the spoolman_<verb>_<noun> pattern (e.g., list_vendors, create_filament). Minor deviations like health_check (object before verb) and trigger_backup are present but not disruptive.
With 34 tools, the server is well above the typical 3-15 range for coherence. While the breadth covers many Spoolman features, the large number makes it heavy and more complex for agents to navigate.
Full CRUD exists for vendors, filaments, and spools, plus exports and settings. However, locations only have list and rename—missing create, delete, and get-by-id—which is a notable gap for that entity.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Enables AI assistants to retrieve event data and execute event management operations in Nunify.
