Maskbolt MCP Server

Maskbolt

Segment Anything (SAM) on your CPU, for AI agents and scripts. Maskbolt is one Rust binary: an MCP server that lets an agent open an image, find every object or click one, look at numbered previews, fix mistakes, and export cutouts, outlines and masks; and a CLI for the same jobs in one command. No Python, no GPU.

• Who it's for: people who want an AI agent (Claude Code, Claude Desktop or another MCP client) or a script to get objects out of photos: game and web makers turning photos into sprites and cutouts, makers who need the outline of a part or an offcut as SVG in millimetres for a laser cutter or a nesting tool, and developers whose agents need masks.

• Use it when you need a transparent cutout, a mask or an outline (SVG with holes, or JSON) of particular objects in an image, or every object found, counted and outlined, on a computer with no GPU, offline after one model download.

• Don't use it for text prompts ("all the dogs": SAM takes points and boxes, which the agent picks from numbered previews), naming what is in an image, video, real-time work (encoding takes about 6.5 s per image on a 16-core desktop CPU), or plain one-subject background removal in bulk, where a dedicated background remover is quicker.

• Compared with other MCP servers: a search of GitHub, mcp.so, Glama and the official MCP Registry on 24 October 2026 found no other MCP server built on Segment Anything. The nearest are background-removal servers, which cut out one main subject and have no clicks, object finding or outline export.

• One click cuts an object out as a transparent PNG; the three nested SAM masks (part, object, group) are one argument away.

• "Find everything" runs grid prompts over the whole image or over overlapping tiles (each re-encoded at full model resolution, so small objects show up), drops masks cut by a tile edge, background patches, duplicates and masks inside others, and says why.

• Every reply that changes masks says how many there are, why candidates were dropped, and which patches still look uncovered ("find more like these"), so an agent knows what is left.

• Exports: overlay PNG (numbered masks, zoomable), cutout PNG, SVG (outer loops and holes, even-odd, optional millimetres), JSON (outlines with holes, area, box, score), labels PNG (one colour per mask).

• Masks are stored cropped to their boxes, so a dense image with thousands of candidates stays small.

Install

Download the archive for your computer from the latest release: maskbolt-v0.1.0-x86_64-pc-windows-msvc.zip, maskbolt-v0.1.0-x86_64-unknown-linux-gnu.tar.gz (glibc 2.35 or newer), maskbolt-v0.1.0-aarch64-apple-darwin.tar.gz or maskbolt-v0.1.0-x86_64-apple-darwin.tar.gz. Check it against the release's SHA256SUMS, extract it and put maskbolt (maskbolt.exe on Windows) on your PATH; maskbolt version prints maskbolt 0.1.0. Each archive also holds the licence, THIRD_PARTY.txt and THIRD_PARTY_NOTICES.md (the licence texts of the Rust dependencies in that build). Or build it with Rust 1.89 or newer:

cargo install --git https://github.com/skulitom/Maskbolt --tag v0.1.0 --locked

Maskbolt is not on crates.io.

The first run downloads the model into a user cache folder and checks its SHA-256:

Cache folder: %LOCALAPPDATA%\maskbolt\models on Windows, $XDG_CACHE_HOME/maskbolt/models or ~/.cache/maskbolt/models elsewhere; set MASKBOLT_MODEL_DIR to use another. maskbolt fetch downloads now. Maskbolt keeps the checked .pth next to the converted safetensors and records the converted file's SHA-256 in <name>.safetensors.sha256; every load re-checks it and rebuilds the file from the .pth if it does not match. Several Maskbolt processes can share the folder (unique temp names, atomic renames). Disk use per model is the checkpoint plus the converted file (ViT-B about 750 MB, MobileSAM about 81 MB). Minimum Rust: 1.89.

CLI

maskbolt cutout examples/chelsea.png --point 200,150 --out cat.png
maskbolt cutout examples/coffee.png --point 300,225 --level largest --fill-holes --out cup-set.png
maskbolt cutout photo.jpg --point 410,220 --exclude 380,300 --box 300,120,520,340 --out thing.png
maskbolt find examples/corn.png --out kernels.json --overlay kernels.png
maskbolt find examples/corn.png --tiles 400 --fill-gaps --out kernels.json --overlay kernels.png
maskbolt find examples/bed.png --grid 12 --min-area 0.01 --max-area 0.3 --drop-hole-views \
    --out offcuts.json --svg offcuts.svg --mm-per-px 0.5
maskbolt mcp --root C:\work\images
maskbolt version

Outputs that already exist are refused unless you pass --force; the input image is never overwritten. One find uses at most 64 tiles and a 48x48 grid; past that it says how many tiles your settings give, about how long they would take, and which tile size fits. A tiled find has no whole-image pass: objects larger than about a third of a tile are dropped, so run a plain find first for big objects. Images are recognised by their content, not their extension, EXIF orientation is applied, and the limit is 100 megapixels.

--level: best (default, highest predicted IoU), smallest (a part), middle (the object), largest (the object with what it holds). find prints a JSON report (counts, drop reasons, timings, what is still uncovered).

MCP

{"mcpServers": {"maskbolt": {"command": "maskbolt", "args": ["mcp", "--root", "C:\\work\\images"]}}}

• Claude Code: the plugin registers this server, rooted at the folder Claude Code runs in, and a maskbolt skill with the loop below. It needs maskbolt on PATH (see Install):

  claude plugin marketplace add skulitom/Maskbolt
  claude plugin install maskbolt@maskbolt
  

  or, inside Claude Code 2.1.275 or later, in one step: /plugin install maskbolt --marketplace skulitom/Maskbolt.

• Claude Desktop (Windows x64): download maskbolt-windows-x64.mcpb from the release, double-click it (or Settings > Extensions > Advanced settings > Install Extension) and choose your image folder.

• MCP Registry: listed as io.github.skulitom/maskbolt, with the Windows bundle and its SHA-256.

• Docker (Linux image): the repository's Dockerfile builds the MCP server; mount your image folder at /data and keep the model in a volume:

  docker build -t maskbolt https://github.com/skulitom/Maskbolt.git
  docker run -i --rm -v "$PWD:/data" -v maskbolt-models:/cache maskbolt
  

  As an MCP server: {"command": "docker", "args": ["run", "-i", "--rm", "-v", "/path/to/images:/data", "-v", "maskbolt-models:/cache", "maskbolt"]}. The server runs as user 10001, so on Linux the folder must be writable by that user for exports. docker run --rm maskbolt version runs the CLI.

Long tiled finds take minutes: the plugin gives Maskbolt's tools a 10-minute timeout; other clients may stop waiting sooner (see Limits).

Tools: maskbolt_open, maskbolt_find, maskbolt_click, maskbolt_view, maskbolt_remove, maskbolt_gaps (add: true clicks the candidates), maskbolt_fill_holes, maskbolt_export. Find and view replies include a numbered PNG; click replies include a zoom on the new mask. The server reads and writes only inside --root (default: the folder it starts in; it refuses to start when that is a drive or file-system root or your home folder). Paths are checked before any file access: UNC and device paths (\\server\share, \\?\, \\.\, //host), other drives and anything .. takes outside the root are refused with one message. Exports never replace an existing file unless the call passes overwrite: true, and never replace the open image. View replies give image_x = region.x + preview_x / scale; previews are at most 1568 px on the long side. On first use the model downloads in the background; maskbolt_open says its size and asks to be called again if it is not done within 25 s.

The loop that works: open; find (add tile: 400 for small or dense objects) or click; view (zoom with region); remove wrong masks; click missed ones; gaps with add: true when replies list uncovered patches; export.

Speed (Ryzen 9 7950X3D, 16 cores, 64 GB, CPU only, release build, 2026-10-23)

Tiles encode 4 at a time (MASKBOLT_ENCODE_THREADS, default 4; each holds about 1.2 GB at its peak; 1 gives about 3.3 GB peak and 332 s for the tiled corn run). Prompts decode on up to 16 threads (MASKBOLT_DECODE_THREADS). For comparison, the Node prototype (8-bit ONNX) took 199 s for the 32x32 corn run and 416 s for the tiled one.

Limits

• CPU only. Encoding is the slow step (about 6.5 s per image or tile with ViT-B); MobileSAM encodes in about 4.2 s here, only 1.5x faster, because candle's CPU convolutions are slow. Memory peaks at 2-3.3 GB for one image and about 7 GB for tiled finds with 4 parallel encodes.
• Long tiled finds can outlast an MCP client's tool timeout (the 400 px corn run, 25 tiles, takes 3.5 minutes; the cap of 64 tiles is about 4 to 10 minutes). There are no progress notifications yet.
• SAM's masks miss thin parts and leave holes; use level, extra include/exclude points, and fill_holes.
• Outlines are simplified with Douglas-Peucker (1.2 px by default; simplify_px in MCP exports); edges move by up to that tolerance. Coordinates are image pixels from the top-left corner (pixel x covers [x, x+1]).
• The gap check is a colour heuristic: it finds look-alikes of what is already masked, not new kinds of object.

Privacy

Maskbolt runs on your computer; its only network request is the one-time model download. Privacy

Licence

MIT. Model weights: Apache-2.0 (Meta's SAM; MobileSAM). src/sam_decoder.rs is adapted from candle (MIT OR Apache-2.0); candle's licence texts are in THIRD_PARTY.txt. Release archives and the MCPB bundle add THIRD_PARTY_NOTICES.md with the licence texts of every Rust dependency in that build. Releasing: see mcpb/PUBLISHING.md.