@cutstack/mcp

Cutstack as tools for Claude, Cursor, Claude Code and any other MCP client: background removal for product photos, batches of up to 200, the automatic check, the review queue and the ZIP.

The server runs on your machine next to the client, speaks MCP over stdio, and calls the Cutstack API with your key. It holds no logic of its own: every tool is one or two calls to /v1, documented at https://trycutstack.com/docs.

Requirements

• Node.js 18 or newer.
• A Cutstack API key: https://trycutstack.com/app/account/api-keys

Setup

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cutstack": {
      "command": "npx",
      "args": ["-y", "@cutstack/mcp"],
      "env": { "CUTSTACK_API_KEY": "csk_live_..." }
    }
  }
}

Claude Code:

claude mcp add cutstack -e CUTSTACK_API_KEY=csk_live_... -- npx -y @cutstack/mcp

Cursor (.cursor/mcp.json): the same JSON as Claude Desktop.

The key is read from the environment only. No tool takes it as an argument, so the model never sees it.

| Variable | Meaning | |---|---| | CUTSTACK_API_KEY | Required. Your key. | | CUTSTACK_BASE_URL | Optional. Default https://trycutstack.com. | | CUTSTACK_MCP_DIR | Optional. Where downloads, previews and ZIPs land when a tool is called without a path. Default: a cutstack-mcp folder in the system temp directory. | | CUTSTACK_MCP_DEBUG | Optional. 1 logs every request to stderr. |

What the agent gets

Tools answer with a short line plus structured data. Pictures never enter the conversation: photos go up from disk or by link, results come back as paths on disk. The one exception is the thumbnail resource, at most 512 px, read only when the agent asks.

| Tool | Credits | What it does | |---|---|---| | list_presets, get_account, list_jobs | free | Presets, balance and limits, your batches. | | create_job | free | An empty batch with default settings. | | add_images | free | Photos from local files or folders, public links, or a ZIP link. Up to 200. | | start_job | 1 per photo | Runs the model. Needs confirm: true; without it the answer only states the cost. sample: 10 runs ten first. | | continue_job | 1 per held photo | Runs the photos held after a sample. Same confirm rule. | | wait_job | free | Holds up to 60 s and returns when something changes. The way to follow a batch. | | get_job | free | Summary, or a page of 50 photos. | | review_queue | free | Only the failed and flagged photos, with reason, area and a thumb URI. | | retry_item | 1, or 2 with tier: heavy | One photo through the model again. | | retry_items | 1 per photo | A list, or every failed photo. | | report_item | free | Report a wrong result; refund when the pixel check agrees. | | apply_settings | free | Other preset, background, size or alignment on finished photos. | | preview_item | free | One photo with other settings, saved to disk. | | get_file | free | Output, cutout, original or thumbnail, saved to disk. | | export_zip | free | The ZIP, with naming pattern, format and extra presets, saved to disk. | | cancel_job, delete_items, delete_job | free | Stop, remove photos, delete a batch. |

Flagged photos are refunded automatically; every tool that charges says how much in its answer.

Resources: cutstack://jobs/{jobId} (manifest, JSON), cutstack://jobs/{jobId}/review (text), cutstack://jobs/{jobId}/items/{itemId}/thumb and .../input-thumb (WebP, at most 512 px).

Prompts: process-catalog (folder, preset, background) and review-flagged (job id).

Development

npm install
npm run build
npm test          # needs a Cutstack server on the fake engine at :3100, see test/stdio.ts

The test mints its own key, uploads a folder, runs a sample, continues, reads the review queue and the thumbnails, downloads files and the ZIP, retries, reports and deletes, all over stdio against the built package.

License

MIT