apancyborg/appsgolem-mcp

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 (src/client.ts); src/server.ts is the thin MCP tool layer over it.
> **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 Code** — one command:
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 — *except*
audio_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).
**Parameters**
| Name | Type | Default | Notes |
| ----------------- | --------- | -------- | ----- |
| url | string | — | **Required.** YouTube watch / share / youtu.be URL. Playlists are rejected. |
| start | string | — | Clip start: "SS", "MM:SS", or "HH:MM:SS" (≤ 300 h). Omit when using clips. |
| end | string | — | Clip end, same formats (≤ 300 h). Omit when using clips. |
| resolution | string | 1080p | 144p · 240p · 360p · 480p · 720p · 1080p · 1440p · 2160p (4K; total cut ≤ 60 min). |
| mode | string | video | 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. |