relief-mcp

An MCP server that turns parts of a photo into a layered 3D relief — like a museum bas-relief — that tilts with the pointer. Claude looks at the photo, picks the parts with boxes, you approve the overlay it shows you, and the server writes one GLB per part plus relief.html, a single self-contained file you can open in any browser — no server needed, no dependencies to install to view it.

Install

With Claude Code:

claude mcp add relief -- npx -y @noon0ri/relief-mcp

From source

git clone https://github.com/noon0ri/relief-mcp.git
claude mcp add relief -s user -- node /path/to/relief-mcp/mcp/server.mjs

Then ask, for example: "Make a relief of the dog and the person in ~/Pictures/dog.jpg".

What you need

• Node 20.9 or newer.
• The first call downloads the segmentation and depth models, about 89 MB, cached at ~/.cache/relief-mcp (override with RELIEF_MCP_CACHE). Later calls use the cache.
• Installing the package pulls in about 530 MB of dependencies (onnxruntime-node and sharp are most of it). The server uses about 1.4 GB of memory while it runs.

How it works / tools

| Tool | What it does | |---|---| | open_image(image) | Loads the photo, returns it with a coordinate grid and its working size (long side at most 1024 px). | | segment_parts(image, parts, open?) | Selects parts, front-most first. Each part is { box: [x0, y0, x1, y1], include?, exclude? }. Returns an overlay and per-part warnings, and opens the overlay image on your screen (open, default true) so you can check it before anything is built. | | make_relief(image, parts, out_dir?, open?) | Writes part-N.glb, relief.html and relief.json to <photo folder>/<photo name>-relief/ and opens relief.html. Refuses if the parts weren't just picked with segment_parts, and asks you to confirm in a dialog (MCP elicitation) before it writes anything — decline or cancel and nothing is written. |

The intended loop: segment_parts shows you an overlay (each part tinted and numbered) and Claude describes what it picked; only after you say it looks right does Claude call make_relief, and you get one more chance to confirm in the dialog before files are written.

Privacy

Your photo never leaves your computer. The only thing downloaded over the network is the model files, from Hugging Face, once, and cached locally. Results are written next to the photo, in <photo folder>/<photo name>-relief/. The overlay image and a small log of confirmation-dialog answers are written to a temp folder (elicit.log and the overlay JPEG) so you can review them later.

Tested / not tested

Checked on macOS (arm64) with Claude Code 2.1.278. Claude Desktop, Windows and Linux have not been run. relief.html was checked in Chrome (headless) and confirmed to open correctly in Safari; other browsers are untested.

License

MIT. The two models it downloads at runtime are each licensed separately and are not redistributed by this package: facebook/sam2.1-hiera-tiny and depth-anything/Depth-Anything-V2-Small-hf, both Apache-2.0.