🧵 Spoolman MCP Server

March 22, 2026 · View on GitHub

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.

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

📄 License

MIT License — see LICENSE for details.

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 💙

Made with ❤️ for the 3D printing community