@cutoutlabs/mcp 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -2
- package/index.js +197 -0
- package/package.json +29 -4
package/README.md
CHANGED
|
@@ -1,3 +1,31 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cutoutlabs/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MCP server for [Cutout Lab](https://www.cutoutlabs.com). It lets AI agents remove image backgrounds from local files or URLs and saves the transparent PNG next to the input.
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
1. Get a free API key at https://www.cutoutlabs.com/background-removal-api
|
|
8
|
+
2. Add the server to your MCP client (Claude Desktop, Cursor, VS Code, and others):
|
|
9
|
+
|
|
10
|
+
```json
|
|
11
|
+
{
|
|
12
|
+
"mcpServers": {
|
|
13
|
+
"cutoutlabs": {
|
|
14
|
+
"command": "npx",
|
|
15
|
+
"args": ["-y", "@cutoutlabs/mcp"],
|
|
16
|
+
"env": { "CUTOUTLABS_API_KEY": "your-key" }
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
No local install? Use the hosted server instead: `https://api.cutoutlabs.com/mcp` with the header `Authorization: Bearer your-key`. The hosted server takes image URLs or base64 and returns the image inline.
|
|
23
|
+
|
|
24
|
+
## Tools
|
|
25
|
+
|
|
26
|
+
- `remove_background`: `input_path` or `image_url`, plus optional `output_path`, `size` (`preview`, `medium`, `hd`, `full`), `format` (`png`, `webp`, `jpg`), `bg_color`, `crop`, `roi` (keep only the subject inside `x1 y1 x2 y2`), `clean_edges` (remove coloured fringes), `overwrite`. Saves the result and returns its path.
|
|
27
|
+
- `get_quota`: free calls left today. The quota resets at 00:00 UTC.
|
|
28
|
+
|
|
29
|
+
## Limits
|
|
30
|
+
|
|
31
|
+
Inputs up to 12 MB. Free daily quota per key during launch.
|
package/index.js
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { access, readFile, stat, writeFile } from "node:fs/promises";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
5
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
6
|
+
import { z } from "zod";
|
|
7
|
+
|
|
8
|
+
const API_URL = (
|
|
9
|
+
process.env.CUTOUTLABS_API_URL ?? "https://api.cutoutlabs.com"
|
|
10
|
+
).replace(/\/$/, "");
|
|
11
|
+
const API_KEY = process.env.CUTOUTLABS_API_KEY;
|
|
12
|
+
const SIGNUP_URL = "https://www.cutoutlabs.com/background-removal-api";
|
|
13
|
+
const MAX_INPUT_BYTES = 12 * 1024 * 1024;
|
|
14
|
+
const EXTENSIONS = {
|
|
15
|
+
"image/png": "png",
|
|
16
|
+
"image/jpeg": "jpg",
|
|
17
|
+
"image/webp": "webp",
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
const text = (value) => ({ content: [{ type: "text", text: value }] });
|
|
21
|
+
const failure = (value) => ({ ...text(value), isError: true });
|
|
22
|
+
const missingKey = () =>
|
|
23
|
+
failure(
|
|
24
|
+
`CUTOUTLABS_API_KEY is not set. Get a free key at ${SIGNUP_URL} and add it to this server's env.`,
|
|
25
|
+
);
|
|
26
|
+
|
|
27
|
+
async function errorMessage(response) {
|
|
28
|
+
const body = await response.json().catch(() => undefined);
|
|
29
|
+
return (
|
|
30
|
+
body?.errors?.[0]?.title ?? `Request failed with HTTP ${response.status}.`
|
|
31
|
+
);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
async function exists(file) {
|
|
35
|
+
return access(file).then(
|
|
36
|
+
() => true,
|
|
37
|
+
() => false,
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const server = new McpServer({
|
|
42
|
+
name: "cutoutlabs",
|
|
43
|
+
title: "Cutout Lab",
|
|
44
|
+
version: "0.2.0",
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
server.registerTool(
|
|
48
|
+
"remove_background",
|
|
49
|
+
{
|
|
50
|
+
title: "Remove image background",
|
|
51
|
+
description:
|
|
52
|
+
"Remove the background from a local image file or an image URL and save the result to disk. Returns the saved file path. Provide exactly one of input_path or image_url. When several objects or a person and a product appear together, the model may keep or drop some of them (for example a hand holding a product); use roi to restrict the subject area. Parts of a subject hidden behind something else cannot be recovered.",
|
|
53
|
+
inputSchema: {
|
|
54
|
+
input_path: z
|
|
55
|
+
.string()
|
|
56
|
+
.optional()
|
|
57
|
+
.describe("Path to a local JPG, PNG or WebP image (max 12 MB)."),
|
|
58
|
+
image_url: z
|
|
59
|
+
.string()
|
|
60
|
+
.url()
|
|
61
|
+
.optional()
|
|
62
|
+
.describe("Public http(s) URL of the source image."),
|
|
63
|
+
output_path: z
|
|
64
|
+
.string()
|
|
65
|
+
.optional()
|
|
66
|
+
.describe(
|
|
67
|
+
"Where to save the result. Defaults to '<input name>-no-bg.<ext>' next to the input, or the current directory for URLs.",
|
|
68
|
+
),
|
|
69
|
+
size: z
|
|
70
|
+
.enum(["preview", "medium", "hd", "full"])
|
|
71
|
+
.default("full")
|
|
72
|
+
.describe(
|
|
73
|
+
"preview ≈ 0.25 MP, medium 1.5 MP, hd 4 MP, full up to 25 MP.",
|
|
74
|
+
),
|
|
75
|
+
format: z.enum(["png", "webp", "jpg"]).default("png"),
|
|
76
|
+
bg_color: z
|
|
77
|
+
.string()
|
|
78
|
+
.optional()
|
|
79
|
+
.describe(
|
|
80
|
+
"Background colour such as ffffff or white. Omit for transparency.",
|
|
81
|
+
),
|
|
82
|
+
crop: z
|
|
83
|
+
.boolean()
|
|
84
|
+
.default(false)
|
|
85
|
+
.describe("Crop the output to the subject."),
|
|
86
|
+
roi: z
|
|
87
|
+
.string()
|
|
88
|
+
.optional()
|
|
89
|
+
.describe(
|
|
90
|
+
"Region of interest as 'x1 y1 x2 y2' in px or %, e.g. '20% 10% 80% 95%'. Only the subject inside this box is kept.",
|
|
91
|
+
),
|
|
92
|
+
clean_edges: z
|
|
93
|
+
.boolean()
|
|
94
|
+
.default(false)
|
|
95
|
+
.describe(
|
|
96
|
+
"Remove coloured fringes from the old background in hair, fur, and soft edges.",
|
|
97
|
+
),
|
|
98
|
+
overwrite: z
|
|
99
|
+
.boolean()
|
|
100
|
+
.default(false)
|
|
101
|
+
.describe("Replace output_path if it already exists."),
|
|
102
|
+
},
|
|
103
|
+
annotations: { destructiveHint: false, openWorldHint: true },
|
|
104
|
+
},
|
|
105
|
+
async ({
|
|
106
|
+
input_path,
|
|
107
|
+
image_url,
|
|
108
|
+
output_path,
|
|
109
|
+
size,
|
|
110
|
+
format,
|
|
111
|
+
bg_color,
|
|
112
|
+
crop,
|
|
113
|
+
roi,
|
|
114
|
+
clean_edges,
|
|
115
|
+
overwrite,
|
|
116
|
+
}) => {
|
|
117
|
+
if (!API_KEY) return missingKey();
|
|
118
|
+
if (Boolean(input_path) === Boolean(image_url))
|
|
119
|
+
return failure("Provide exactly one of input_path or image_url.");
|
|
120
|
+
|
|
121
|
+
const form = new FormData();
|
|
122
|
+
if (input_path) {
|
|
123
|
+
const source = path.resolve(input_path);
|
|
124
|
+
const info = await stat(source).catch(() => undefined);
|
|
125
|
+
if (!info?.isFile()) return failure(`File not found: ${source}`);
|
|
126
|
+
if (info.size > MAX_INPUT_BYTES) return failure("Image exceeds 12 MB.");
|
|
127
|
+
form.append(
|
|
128
|
+
"image_file",
|
|
129
|
+
new Blob([await readFile(source)]),
|
|
130
|
+
path.basename(source),
|
|
131
|
+
);
|
|
132
|
+
} else {
|
|
133
|
+
form.append("image_url", image_url);
|
|
134
|
+
}
|
|
135
|
+
form.append("size", size);
|
|
136
|
+
form.append("format", format);
|
|
137
|
+
form.append("crop", String(crop));
|
|
138
|
+
form.append("clean_edges", String(clean_edges));
|
|
139
|
+
if (roi) form.append("roi", roi);
|
|
140
|
+
if (bg_color) form.append("bg_color", bg_color);
|
|
141
|
+
|
|
142
|
+
const response = await fetch(`${API_URL}/v1.0/removebg`, {
|
|
143
|
+
method: "POST",
|
|
144
|
+
headers: { "X-Api-Key": API_KEY },
|
|
145
|
+
body: form,
|
|
146
|
+
signal: AbortSignal.timeout(180_000),
|
|
147
|
+
});
|
|
148
|
+
if (!response.ok) return failure(await errorMessage(response));
|
|
149
|
+
|
|
150
|
+
const extension =
|
|
151
|
+
EXTENSIONS[response.headers.get("content-type")] ?? format;
|
|
152
|
+
const target = path.resolve(
|
|
153
|
+
output_path ??
|
|
154
|
+
(input_path
|
|
155
|
+
? path.join(
|
|
156
|
+
path.dirname(input_path),
|
|
157
|
+
`${path.parse(input_path).name}-no-bg.${extension}`,
|
|
158
|
+
)
|
|
159
|
+
: `cutout-${Date.now()}.${extension}`),
|
|
160
|
+
);
|
|
161
|
+
if (!overwrite && (await exists(target)))
|
|
162
|
+
return failure(
|
|
163
|
+
`${target} already exists. Pass overwrite: true or another output_path.`,
|
|
164
|
+
);
|
|
165
|
+
await writeFile(target, Buffer.from(await response.arrayBuffer()));
|
|
166
|
+
|
|
167
|
+
const width = response.headers.get("x-width");
|
|
168
|
+
const height = response.headers.get("x-height");
|
|
169
|
+
const remaining = response.headers.get("x-quota-remaining");
|
|
170
|
+
return text(
|
|
171
|
+
`Saved ${target}${width && height ? ` (${width}×${height})` : ""}. ${remaining ?? "?"} free calls left today.`,
|
|
172
|
+
);
|
|
173
|
+
},
|
|
174
|
+
);
|
|
175
|
+
|
|
176
|
+
server.registerTool(
|
|
177
|
+
"get_quota",
|
|
178
|
+
{
|
|
179
|
+
title: "Check remaining free calls",
|
|
180
|
+
description: "Return how many free remove_background calls remain today.",
|
|
181
|
+
annotations: { readOnlyHint: true },
|
|
182
|
+
},
|
|
183
|
+
async () => {
|
|
184
|
+
if (!API_KEY) return missingKey();
|
|
185
|
+
const response = await fetch(`${API_URL}/v1.0/account`, {
|
|
186
|
+
headers: { "X-Api-Key": API_KEY },
|
|
187
|
+
signal: AbortSignal.timeout(30_000),
|
|
188
|
+
});
|
|
189
|
+
if (!response.ok) return failure(await errorMessage(response));
|
|
190
|
+
const body = await response.json();
|
|
191
|
+
return text(
|
|
192
|
+
`${body.data.attributes.api.free_calls} free calls left today. Resets at 00:00 UTC.`,
|
|
193
|
+
);
|
|
194
|
+
},
|
|
195
|
+
);
|
|
196
|
+
|
|
197
|
+
await server.connect(new StdioServerTransport());
|
package/package.json
CHANGED
|
@@ -1,6 +1,31 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cutoutlabs/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "MCP server for Cutout Lab: remove image backgrounds from local files or URLs and save transparent PNGs.",
|
|
5
|
+
"mcpName": "com.cutoutlabs/mcp",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"cutoutlabs-mcp": "index.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"index.js",
|
|
12
|
+
"README.md"
|
|
13
|
+
],
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=20"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"mcp",
|
|
19
|
+
"model-context-protocol",
|
|
20
|
+
"background-removal",
|
|
21
|
+
"remove-background",
|
|
22
|
+
"removebg",
|
|
23
|
+
"transparent-png"
|
|
24
|
+
],
|
|
25
|
+
"homepage": "https://www.cutoutlabs.com/background-removal-api",
|
|
26
|
+
"license": "MIT",
|
|
27
|
+
"dependencies": {
|
|
28
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
29
|
+
"zod": "^4.0.0"
|
|
30
|
+
}
|
|
31
|
+
}
|