An MCP server for the AppsGolem YouTube
cutter API. It lets an AI agent (Claude Desktop, Claude Code, Cursor, …) cut
clips from YouTube videos — in any format the web cutter supports — and get a
direct download URL back. The REST logic lives in a small, dependency-light
client (); is the thin MCP tool layer over it.
Cut clips from YouTube videos in any format and get a direct download URL.
API key
APPSGOLEM_API_KEY, APPSGOLEM_API_BASE
पिछली जाँच
2026-11-09
स्टार
—
टूल
—
अपटाइम
—
src/client.ts
src/server.ts
Get your API key → appsgolem.com/agents — sign up, add prepaid
credits, and generate a key (ag_live_…). That page also has copy-paste
setup for Claude Code, Codex, Cursor, and any MCP client, plus a prompt
cookbook.
Requirements
Node.js >= 18 (uses the global fetch).
An AppsGolem API key (ag_live_…) — get one at
appsgolem.com/agents (sign up → add credits → generate a key in
your dashboard). Credits are prepaid; buy a pack or a subscription, no
auto-renewal required.
Install / connect (no manual install)
npx fetches and runs the server on demand — nothing to install globally.
Claude Desktop / Cursor — add to the client's MCP config (e.g.
claude_desktop_config.json):
claude mcp add appsgolem -e APPSGOLEM_API_KEY=ag_live_… -- npx -y appsgolem-mcp
The server speaks MCP over stdio (the transport those clients use). A
missing APPSGOLEM_API_KEY is not fatal at startup — the server still starts
and advertises its tools; each call then returns a clear config_error telling
you to set the key.
Configuration
Env var
Required
Default
Notes
APPSGOLEM_API_KEY
yes
—
Your ag_live_… key.
APPSGOLEM_API_BASE
no
https://appsgolem.com
Override for self-host / dev.
Pricing
1 produced clip = 1 credit. 2160p (4K) = 4 credits per clip — exceptaudio_only, which stays 1. A source longer than 2 h adds +1 once
per job, but only when its duration is known (the surcharge is skipped if the
probe can't determine it). A batch/stitch of N clips costs N per-clip.
Failed cuts are never billed.
Tools
The server exposes three tools. A call that passes MCP input-schema
validation returns a structured result — the API's own JSON on success, or
{ "error": … } on any handler/API failure — and never raises a protocol-level
error, so an agent always gets a usable object. (Invalid tool arguments are
rejected by the MCP SDK before the handler runs, as a text-only isError
result.)
1. cut_youtube_video
Cut a clip (or a batch of clips) from a YouTube video. By default it waits
until the clip is produced and returns its status (including a download_url
once a download token is ready); set wait: false to submit and return
immediately with the current job (its state is normally queued after dispatch).
video · audio_only · both · nosound · short · gif · frames (see Modes below).
audio_format
string
—
The audio_only output format: mp3 · m4a · wav · flac (server defaults to mp3). both always produces MP3.
bitrate
string
—
Lossy-audio bitrate 320 · 256 · 192 · 128 (default 320): MP3/M4A in audio_only, MP3 in both; ignored for WAV/FLAC.
fast
boolean
false
Stream-copy (≈10× faster, keyframe-aligned); video / nosound / both only. Mutually exclusive with a non-1× speed — if both are set, fast wins and speed is forced to 1.0.
speed
number
1.0
Playback speed 0.5 · 1 · 1.25 · 1.5 · 2. video / nosound / both / audio_only.
interval_ms
integer
2000
frames sampling interval: 100 · 500 · 1000 · 2000 · 5000 · 10000 (non-sheet extraction is capped at 1,800 JPGs total across all clips).
burn_ts
boolean
false
frames: burn the source timestamp onto each JPG.
sheet
boolean
false
frames: return a single contact-sheet JPG (2–80 frames, single clip). Setting it disables burn_ts.
clips
array
—
An array of 1–10{ start, end } ranges instead ofstart/end (an empty array is rejected).
stitch
boolean
false
With 2+ clips, join them into one file (else a zip of clips); ignored for a single clip. video / audio_only / both / short / nosound.
idempotency_key
string
—
A stable key (≤ 200 chars) so a retried request reuses the same job (sent as the Idempotency-Key header).
wait
boolean
true
Poll until ready, up to the timeout_seconds polling deadline.
timeout_seconds
integer
300
Polling deadline in seconds (default 300). It bounds the polling only — the initial submission and one in-flight status request (each up to a 30 s request timeout) can extend total wall-clock.
Returns (wait: true, default) — the produced job status. download_url is
present once a download token is available; if it isn't yet, poll again:
Returns (wait: false) — the job immediately, with its current state
(normally queued after dispatch) and no download_url yet; poll
get_cut_status with the id (or fetch poll_url):
If the wait times out before the clip is ready, the result carries
"still_processing": true and the job id — poll get_cut_status with that
id. If the job reaches a terminal failure, the result is
{ "error": "cut_failed", "state": "failed" | "refunded", "id": … } (and no
credit is charged).
2. get_cut_status
Check a cut job by its id. Use it to poll a job started with
cut_youtube_video(wait=false) or one that timed out.
Name
Type
Notes
job_id
string
Required. The job id (a UUID) returned by cut_youtube_video.
Returns — the job's state; once produced/delivered it also carries a
download_url when a download token is available (otherwise poll again):
States progress accepted → queued → produced → delivered, or
failed → refunded on error.
3. get_account_balance
Return the API account's spendable credit balance and current hourly cap. No
parameters.
Returns
{ "balance": 412, "hourly_cap": 60 }
Modes
mode
Output
Notable options
video
Video file, no watermark — normally MP4; fast preserves the source container (e.g. WebM at high res)
resolution, fast, speed
audio_only
mp3 / m4a / wav / flac
audio_format, bitrate, speed
both
Video + MP3 together, as a zip (fast may preserve the video's source container)
bitrate, fast, speed
nosound
Video with no audio track — normally MP4; fast preserves the source container
resolution, fast, speed
short
Portrait 9:16 — AI smart-crop when applicable, else a letterbox-blur fallback whose exact aspect depends on the source (Shorts / Reels / TikTok)
resolution
gif
Animated GIF (≤ 5 min; no multi-clip)
resolution
frames
JPG stills
interval_ms, burn_ts, sheet
Example prompts
Because the agent picks the parameters from your request, you drive it in plain
language:
"Cut 0:30 to 1:15 from https://youtu.be/dQw4w9WgXcQ in 1080p." →
cut_youtube_video(url, start="0:30", end="1:15")
"Grab the audio of that video from 2:00 to 5:00 as an mp3." →
mode="audio_only", audio_format="mp3"
"Make a vertical short of the 10:00–10:45 highlight." →
mode="short", start="10:00", end="10:45"
"Turn 0:05–0:12 into a GIF." → mode="gif"
"Extract a contact sheet of frames every 5 seconds from 1:00 to 2:00." →
mode="frames", interval_ms=5000, sheet=true
"Stitch 0:10–0:20 and 1:00–1:10 into one clip." →
clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true
"Do a fast, stream-copy cut of 0:00–0:30." → fast=true
"How many API credits do I have left?" → get_account_balance()
Result & error shapes
Every result from a handler is a plain object (MCP argument-validation
failures are the exception — see the Tools note above). On failure the object has an error code
(the tool call still succeeds):
error
When
config_error
APPSGOLEM_API_KEY is missing.
invalid_api_key
The key was rejected (401).
invalid_job_id
job_id isn't a UUID.
not_found
No such job for this account (404).
cut_failed
The job reached failed/refunded (never billed).
network_error
Connection/transport failure or request timeout.
bad_request
The configured API base/path couldn't be built into a URL.
http_error
A ≥400 response whose JSON body isn't an { error: … } object (carries status).
bad_response
A success response whose body isn't a JSON object (array/scalar/null), or — with wait: true — a cut submission that came back without a usable job id.
API-level errors — validation 400, 402 insufficient_credits,
404 not_found, 409 idempotency_conflict / duplicate_in_flight,
429 rate_limited, and 503 rate_limiter_unavailable / database_busy — are
returned as the API's own error body plus a status field. A 429 also
includes retry_after (seconds, from Retry-After) plus a reason
(submission_cap · request_rate · poll_rate) so an agent can tell which
limit it hit and back off correctly. A 503 is usually transient (retry after
a short delay), but a persistent 503 is a server-side problem to report — not
to retry indefinitely.
Status polling is not rate-limited for normal use — checking a job's
progress never counts against your submissions/hour cap. You never need to
throttle get_cut_status yourself: cut_youtube_video(wait=true) polls and
paces for you (honoring the server's poll_after cadence and any Retry-After),
so a single tool call handles even long jobs.
Produced download links expire after a bounded window (~72 hours by default on
appsgolem.com; configurable per deployment) — fetch the file within it.
A relative download_url (the API returns a path) is resolved to a full URL
against the configured API base only when the result stays on that origin.
Any download_url that resolves off the API's origin — an absolute URL to
another host, or a relative path that escapes the origin — is dropped for
safety: the field is removed and the result carries download_url_dropped: true,
so you can tell it apart from a job that simply isn't produced yet. When
cut_youtube_video is waiting for you (wait=true, the default), an off-origin
link surfaces as a download_url_unsafe error instead of handing back a bad URL.
Develop
npm install
npm run build # tsc -> dist/
npm test # builds, then runs node --test (no network)
npm start # run the stdio server locally (key needed for calls, not startup)
Publishing
npm publish (from this directory) makes npx appsgolem-mcp work for everyone.
The prepare script builds dist/ automatically on install/publish.
अभी टूल सूची नहीं है। रिमोट सर्वर को पहले हेल्थ चेक के बाद सूची मिलती है।
FAQ
सवाल
AppsGolem YouTube Cutter कैसे इंस्टॉल करें?
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
क्या AppsGolem YouTube Cutter के लिए API key चाहिए?
पब्लिशर ने ये एनवायरनमेंट वेरिएबल बताए हैं: APPSGOLEM_API_KEY, APPSGOLEM_API_BASE।
AppsGolem YouTube Cutter कौन सा ट्रांसपोर्ट इस्तेमाल करता है?
AppsGolem YouTube Cutter stdio पर लोकल चलता है।
AppsGolem YouTube Cutter की पिछली जाँच कब हुई थी?
पिछली जाँच 2026-11-09 को हुई। Cut clips from YouTube videos in any format and get a direct download URL.