Skip to content
Back to search

spoolman-mcp-go

MCP server for Spoolman (3D printing filament inventory) - Go, stdio + Streamable HTTP, bearer auth, tiny Docker image

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/virtualben89--spoolman-mcp-go/badge.svg)](/listings/virtualben89--spoolman-mcp-go)

HTML

<a href="/listings/virtualben89--spoolman-mcp-go"><img src="/api/listings/virtualben89--spoolman-mcp-go/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Docker (HTTP)

docker run -d --name spoolman-mcp -p 8080:8080 \
  -e SPOOLMAN_URL=http://spoolman:7912 \
  -e MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  ghcr.io/virtualben89/spoolman-mcp-go:latest

The MCP endpoint is `http://<host>:8080/mcp` (legacy SSE: `/sse`). Clients must send `Authorization: Bearer <token>`. See [`examples/docker-compose.yml`](examples/docker-compose.yml).

Docker (stdio)

docker run -i --rm -e MCP_TRANSPORT=stdio -e SPOOLMAN_URL=http://spoolman:7912 \
  ghcr.io/virtualben89/spoolman-mcp-go:latest

Binary

Download a binary from [Releases](https://github.com/virtualben89/spoolman-mcp-go/releases) or `go install github.com/virtualben89/spoolman-mcp-go/cmd/spoolman-mcp@latest`, then:

SPOOLMAN_URL=http://spoolman:7912 spoolman-mcp            # stdio (default)
SPOOLMAN_URL=http://spoolman:7912 MCP_TRANSPORT=http MCP_AUTH_TOKEN=... spoolman-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 237 lines
  1. # spoolman-mcp-go
  2. A fast, dependency-free [Model Context Protocol](https://modelcontextprotocol.io) server for
  3. [Spoolman](https://github.com/Donkie/Spoolman), the self-hosted 3D printing filament inventory.
  4. It lets any MCP-capable AI agent (Claude Desktop/Code, ChatGPT, Cursor, VS Code Copilot, Gemini CLI,
  5. Codex, n8n, Hermes, LibreChat, Open WebUI, …) **read and manage** your vendors, filaments and spools.
  6. - **Single static Go binary**, built on the official [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)
  7. - **Transports:** `stdio`, **Streamable HTTP** (`/mcp`) and legacy **HTTP+SSE** (`/sse`)
  8. - **Bearer token auth** for HTTP (multiple tokens, constant-time compare, refuses to start unauthenticated)
  9. - **Read & write:** 38 tools covering the full Spoolman API, including NFC tags, extra fields, settings,
  10. backups and import from the SpoolmanDB catalogue
  11. - **Safety switches:** `READ_ONLY=true` hides all write tools, `ALLOW_DELETE=false` hides delete tools,
  12. and every delete requires `confirm=true`
  13. - **Upstream auth** towards Spoolman (Bearer, Basic or custom headers, e.g. Cloudflare Access) for
  14. instances behind a reverse proxy
  15. - **Tiny image:** `FROM scratch`, non-root, ~14 MB, `linux/amd64`, `linux/arm64`, `linux/arm/v7`
  16. - Portable tool schemas (no `$ref`, no union types) so strict clients such as Gemini and OpenAI accept them
  17. ## Quick start
  18. ### Docker (HTTP)
  19. ```bash
  20. docker run -d --name spoolman-mcp -p 8080:8080 \
  21. -e SPOOLMAN_URL=http://spoolman:7912 \
  22. -e MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  23. ghcr.io/virtualben89/spoolman-mcp-go:latest
  24. ```
  25. The MCP endpoint is `http://<host>:8080/mcp` (legacy SSE: `/sse`). Clients must send
  26. `Authorization: Bearer <token>`. See [`examples/docker-compose.yml`](examples/docker-compose.yml).
  27. ### Docker (stdio)
  28. ```bash
  29. docker run -i --rm -e MCP_TRANSPORT=stdio -e SPOOLMAN_URL=http://spoolman:7912 \
  30. ghcr.io/virtualben89/spoolman-mcp-go:latest
  31. ```
  32. ### Binary
  33. Download a binary from [Releases](https://github.com/virtualben89/spoolman-mcp-go/releases) or
  34. `go install github.com/virtualben89/spoolman-mcp-go/cmd/spoolman-mcp@latest`, then:
  35. ```bash
  36. SPOOLMAN_URL=http://spoolman:7912 spoolman-mcp # stdio (default)
  37. SPOOLMAN_URL=http://spoolman:7912 MCP_TRANSPORT=http MCP_AUTH_TOKEN=... spoolman-mcp
  38. ```
  39. ## Configuration
  40. All options can be set as environment variables (or flags, see `spoolman-mcp -h`).
  41. Secrets are read from env only; every secret also supports a `*_FILE` variant (Docker secrets).
  42. | Variable | Default | Description |
  43. |---|---|---|
  44. | `SPOOLMAN_URL` | – (required) | Spoolman base URL, e.g. `http://spoolman:7912` (`/api/v1` is optional) |
  45. | `SPOOLMAN_TIMEOUT` | `30s` | Timeout for Spoolman requests |
  46. | `SPOOLMAN_BEARER_TOKEN` | – | Send `Authorization: Bearer …` to Spoolman |
  47. | `SPOOLMAN_BASIC_USER` / `SPOOLMAN_BASIC_PASSWORD` | – | Send HTTP Basic auth to Spoolman |
  48. | `SPOOLMAN_HEADERS` | – | Extra headers, `Name: value; Other: value` (e.g. Cloudflare Access service tokens) |
  49. | `SPOOLMAN_CA_FILE` | – | Extra CA bundle (PEM) for a private CA |
  50. | `SPOOLMAN_INSECURE_SKIP_VERIFY` | `false` | Skip TLS verification (not recommended) |
  51. | `MCP_TRANSPORT` | `stdio` (`http` in Docker) | `stdio` or `http` |
  52. | `MCP_HTTP_ADDR` | `:8080` | Listen address |
  53. | `MCP_HTTP_PATH` | `/mcp` | Streamable HTTP endpoint |
  54. | `MCP_AUTH_TOKEN` | – | Bearer token(s) for HTTP clients, comma-separated, min. 16 chars. **Required** for HTTP |
  55. | `MCP_ALLOW_NO_AUTH` | `false` | Explicitly allow HTTP without a token (only behind an authenticating proxy) |
  56. | `MCP_HTTP_ENABLE_SSE` | `true` | Also serve the legacy HTTP+SSE transport on `/sse` |
  57. | `MCP_HTTP_STATELESS` | `false` | Stateless Streamable HTTP (no sessions; good for load balancers/serverless) |
  58. | `MCP_HTTP_JSON_RESPONSE` | `false` | Reply with `application/json` instead of SSE streams |
  59. | `MCP_HTTP_SESSION_TIMEOUT` | `30m` | Close idle sessions after this duration (`0` = never) |
  60. | `READ_ONLY` | `false` | Only expose read tools |
  61. | `ALLOW_DELETE` | `true` | Expose delete tools (they still require `confirm=true`) |
  62. | `TOOL_PREFIX` | – | Prefix for tool names, e.g. `spoolman_` for clients without namespacing |
  63. | `DEFAULT_LIMIT` | `50` | Default page size of list tools (`0` = unlimited) |
  64. | `LOG_LEVEL` / `LOG_FORMAT` | `info` / `text` | `debug…error` / `text` or `json` (always logged to stderr) |
  65. HTTP endpoints: `/mcp` (+ `/sse`) require the bearer token; `/healthz` (liveness) and `/readyz`
  66. (checks Spoolman) are public. The image contains a `healthcheck` subcommand used by Docker's `HEALTHCHECK`.
  67. > **Security note:** the token protects the MCP endpoint, but it travels in plain text over HTTP.
  68. > Put the server behind TLS (e.g. Traefik/Caddy) or keep it on a trusted network/VPN.
  69. > stdio has no network exposure and therefore no token.
  70. ## Client configuration
  71. <details><summary><b>Claude Code</b></summary>
  72. ```bash
  73. # HTTP
  74. claude mcp add --transport http spoolman https://spoolman-mcp.example.com/mcp \
  75. --header "Authorization: Bearer $TOKEN"
  76. # stdio
  77. claude mcp add spoolman -e SPOOLMAN_URL=http://spoolman:7912 -- spoolman-mcp
  78. ```
  79. </details>
  80. <details><summary><b>Claude Desktop / Cursor / Windsurf / generic <code>mcpServers</code> JSON</b></summary>
  81. ```json
  82. {
  83. "mcpServers": {
  84. "spoolman": {
  85. "command": "spoolman-mcp",
  86. "env": { "SPOOLMAN_URL": "http://spoolman:7912" }
  87. }
  88. }
  89. }
  90. ```
  91. Via Docker instead of a local binary:
  92. ```json
  93. {
  94. "mcpServers": {
  95. "spoolman": {
  96. "command": "docker",
  97. "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT=stdio", "-e", "SPOOLMAN_URL",
  98. "ghcr.io/virtualben89/spoolman-mcp-go:latest"],
  99. "env": { "SPOOLMAN_URL": "http://spoolman:7912" }
  100. }
  101. }
  102. }
  103. ```
  104. Remote HTTP (Cursor and others that support `url` + `headers`):
  105. ```json
  106. {
  107. "mcpServers": {
  108. "spoolman": {
  109. "url": "https://spoolman-mcp.example.com/mcp",
  110. "headers": { "Authorization": "Bearer <token>" }
  111. }
  112. }
  113. }
  114. ```
  115. </details>
  116. <details><summary><b>VS Code (GitHub Copilot)</b> – <code>.vscode/mcp.json</code></summary>
  117. ```json
  118. {
  119. "inputs": [{ "type": "promptString", "id": "spoolman-token", "description": "Spoolman MCP token", "password": true }],
  120. "servers": {
  121. "spoolman": {
  122. "type": "http",
  123. "url": "https://spoolman-mcp.example.com/mcp",
  124. "headers": { "Authorization": "Bearer ${input:spoolman-token}" }
  125. }
  126. }
  127. }
  128. ```
  129. </details>
  130. <details><summary><b>Gemini CLI</b> – <code>~/.gemini/settings.json</code></summary>
  131. ```json
  132. {
  133. "mcpServers": {
  134. "spoolman": {
  135. "httpUrl": "https://spoolman-mcp.example.com/mcp",
  136. "headers": { "Authorization": "Bearer <token>" }
  137. }
  138. }
  139. }
  140. ```
  141. </details>
  142. <details><summary><b>OpenAI Codex CLI</b> – <code>~/.codex/config.toml</code></summary>
  143. ```toml
  144. [mcp_servers.spoolman]
  145. url = "https://spoolman-mcp.example.com/mcp"
  146. bearer_token_env_var = "SPOOLMAN_MCP_TOKEN"
  147. ```
  148. </details>
  149. <details><summary><b>Hermes Agent</b> – <code>config.yaml</code></summary>
  150. ```yaml
  151. mcp_servers:
  152. spoolman:
  153. url: https://spoolman-mcp.example.com/mcp
  154. headers:
  155. Authorization: "Bearer ${SPOOLMAN_MCP_TOKEN}"
  156. ```
  157. </details>
  158. <details><summary><b>n8n, LibreChat, Open WebUI, OpenAI Agents SDK, …</b></summary>
  159. Use the Streamable HTTP URL `https://<host>/mcp` with header `Authorization: Bearer <token>`.
  160. Older clients that only speak the 2024 HTTP+SSE transport can use `https://<host>/sse`.
  161. </details>
  162. ## Tools
  163. | Read | Write | Delete (`confirm=true`) |
  164. |---|---|---|
  165. | `get_info` – version & health | `create_vendor`, `update_vendor` | `delete_spool` |
  166. | `search` – across spools, filaments, vendors | `create_filament`, `update_filament` | `delete_filament` |
  167. | `list_spools`, `get_spool` | `import_external_filament` – from SpoolmanDB | `delete_vendor` |
  168. | `list_spool_groups` – inventory per filament/vendor/material/location | `create_spool`, `update_spool` | `delete_extra_field` |
  169. | `list_filaments`, `get_filament` | `use_spool` – book consumption (g or mm) | `unlink_tag` |
  170. | `list_vendors`, `get_vendor` | `measure_spool` – update from scale weight | |
  171. | `list_distinct_values` – materials, locations, article/lot numbers | `rename_location`, `rename_spool_field_value` | |
  172. | `list_extra_fields`, `list_extra_field_values` | `set_extra_field` | |
  173. | `get_settings` | `set_setting`, `create_backup` | |
  174. | `search_external_filaments`, `list_external_materials` | `link_tag`, `report_tag_scan` | |
  175. | `export` – CSV/JSON | | |
  176. | `list_tag_readers` | | |
  177. Notes for agents:
  178. - Update tools are partial: only given fields change. Use `clear_fields` to set fields to empty.
  179. - `extra` values are passed as native JSON values and encoded for Spoolman automatically.
  180. - List tools return `{total, count, offset, limit, has_more, items}`.
  181. - All tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients
  182. can auto-approve reads and ask before writes.
  183. ## Development
  184. ```bash
  185. go test -race ./...
  186. # integration tests against a DISPOSABLE Spoolman (creates and deletes data!)
  187. docker run -d -p 7912:8000 ghcr.io/donkie/spoolman:latest
  188. SPOOLMAN_TEST_URL=http://localhost:7912 go test -tags integration ./internal/tools/
  189. ```
  190. CI runs unit tests, the integration suite against a real Spoolman service container, an image smoke
  191. test, and publishes multi-arch images to GHCR (`edge` from `main`, semver + `latest` from tags).
  192. ## License
  193. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.