@fanyzp/ytdlp-mcp 0.0.0-stage → 1.0.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/LICENSE +21 -0
- package/PROMPT.md +20 -0
- package/README.md +68 -2
- package/examples/cline.md +19 -0
- package/examples/codex.md +15 -0
- package/examples/cursor-copilot.md +15 -0
- package/examples/gemini-claude.json +11 -0
- package/examples/hermes.sh +6 -0
- package/examples/openclaw.md +12 -0
- package/examples/opencode-plugin.md +25 -0
- package/examples/opencode.json +13 -0
- package/examples/pi.md +14 -0
- package/glama.json +1 -0
- package/package.json +62 -4
- package/scripts/install.mjs +430 -0
- package/server.json +54 -0
- package/skill/SKILL.md +71 -0
- package/smithery.yaml +37 -0
- package/src/index.js +717 -0
- package/src/lib.js +293 -0
- package/src/schemas.js +96 -0
- package/src/search.js +37 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 fanyzp
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/PROMPT.md
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Copy this prompt to your AI
|
|
2
|
+
|
|
3
|
+
```text
|
|
4
|
+
Install the ytdlp MCP server from https://github.com/fanyzp/ytdlp-mcp
|
|
5
|
+
and let the AI do the rest:
|
|
6
|
+
|
|
7
|
+
1. Clone the repo.
|
|
8
|
+
2. Make sure `yt-dlp` and `ffmpeg` are on PATH. If either is missing,
|
|
9
|
+
install it first (winget on Windows, brew on macOS, distro package
|
|
10
|
+
on Linux) and stop if you cannot.
|
|
11
|
+
3. Run `npm run setup` and pick install targets in the checklist.
|
|
12
|
+
4. Verify: `hermes mcp list` shows ytdlp enabled (if Hermes is present).
|
|
13
|
+
5. Report which targets were installed.
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
One line version:
|
|
17
|
+
|
|
18
|
+
```text
|
|
19
|
+
Install https://github.com/fanyzp/ytdlp-mcp: clone, ensure yt-dlp and ffmpeg exist, run npm run setup, report results.
|
|
20
|
+
```
|
package/README.md
CHANGED
|
@@ -1,3 +1,69 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="assets/banner.png">
|
|
3
|
+
<img src="assets/banner.png" alt="ytdlp-mcp" width="100%">
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
|
|
9
|
+
<img src="https://img.shields.io/badge/version-v1.0.0-blue" alt="Version">
|
|
10
|
+
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node.js">
|
|
11
|
+
<img src="https://img.shields.io/badge/platforms-linux_macos_windows-lightgrey" alt="Platforms">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<strong>An MCP server that lets AI agents inspect, download, and convert video and audio using yt-dlp and FFmpeg through natural language instructions.</strong>
|
|
16
|
+
</p>
|
|
17
|
+
|
|
18
|
+
## Example
|
|
19
|
+
|
|
20
|
+
Send a link, get the file. Or type `/ytdlp-mcp` in OpenCode, Gemini CLI, or Claude Code:
|
|
21
|
+
|
|
22
|
+

|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
git clone https://github.com/fanyzp/ytdlp-mcp.git && cd ytdlp-mcp && npm run setup
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Requires `yt-dlp`, `ffmpeg`, Node 18. Or copy [PROMPT.md](PROMPT.md) into any AI agent and let it install for you.
|
|
31
|
+
|
|
32
|
+
## Tools
|
|
33
|
+
|
|
34
|
+
| Tool | What it does |
|
|
35
|
+
| --------------- | ----------------------------------------------------------------- |
|
|
36
|
+
| `probe` | Read title, duration, uploader, views, thumbnail, and description |
|
|
37
|
+
| `formats` | List available media formats, quality, and estimated sizes |
|
|
38
|
+
| `supported` | Check whether a URL matches a locally installed yt-dlp extractor |
|
|
39
|
+
| `inspect` | Recommend a download action, quality, and available resolutions |
|
|
40
|
+
| `get_video` | Download video, default output is MP4 |
|
|
41
|
+
| `get_audio` | Extract audio as Opus, MP3, or M4A |
|
|
42
|
+
| `get_subtitles` | Download manual or auto-generated subtitles as VTT |
|
|
43
|
+
| `advise` | Answer yt-dlp configuration questions |
|
|
44
|
+
| `queue` | Preview a batch of URLs and per-item download plans |
|
|
45
|
+
| `fetch_all` | Download a batch of URLs with optional delays |
|
|
46
|
+
| `watch` | List entries from a playlist or channel without downloading |
|
|
47
|
+
| `search` | Search YouTube or SoundCloud and return compact metadata |
|
|
48
|
+
| `convert` | Re-encode a local video using FFmpeg presets |
|
|
49
|
+
|
|
50
|
+
### Search providers
|
|
51
|
+
|
|
52
|
+
The `search` tool uses yt-dlp search extractor prefixes. YouTube (`ytsearch`) and SoundCloud (`scsearch`) were verified against the installed yt-dlp build. Other installed extractors include search-related entries, but not all provide a supported search prefix, so they are not exposed as providers unless the prefix works in a real query. Search results return metadata only and are limited to 1-50 items.
|
|
53
|
+
|
|
54
|
+
| Provider | yt-dlp prefix |
|
|
55
|
+
| ------------ | ------------- |
|
|
56
|
+
| `youtube` | `ytsearch` |
|
|
57
|
+
| `soundcloud` | `scsearch` |
|
|
58
|
+
|
|
59
|
+
## Env
|
|
60
|
+
|
|
61
|
+
| Variable | Default |
|
|
62
|
+
| -------------------------- | ----------------------- |
|
|
63
|
+
| `YTDLP_DOWNLOAD_DIR` | `~/Downloads/ytdlp-mcp` |
|
|
64
|
+
| `YTDLP_COOKIES_FILE` | empty |
|
|
65
|
+
| `YTDLP_BIN` / `FFMPEG_BIN` | `yt-dlp` / `ffmpeg` |
|
|
66
|
+
|
|
67
|
+
## License
|
|
68
|
+
|
|
69
|
+
MIT: [LICENSE](LICENSE)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Cline (skills only)
|
|
2
|
+
|
|
3
|
+
Cline reads skills but manages MCP servers through its own UI. Link the skill:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
mkdir -p ~/.cline/skills
|
|
7
|
+
ln -s /path/to/ytdlp-mcp/skill ~/.cline/skills/ytdlp-mcp
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Then add the server manually in Cline MCP settings:
|
|
11
|
+
|
|
12
|
+
- command: `node`
|
|
13
|
+
- args: `/path/to/ytdlp-mcp/src/index.js`
|
|
14
|
+
|
|
15
|
+
Or let the installer link the skill:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
node scripts/install.mjs --only=cline
|
|
19
|
+
```
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Codex CLI (`~/.codex/config.toml`)
|
|
2
|
+
|
|
3
|
+
```toml
|
|
4
|
+
[mcp_servers.ytdlp]
|
|
5
|
+
command = "node"
|
|
6
|
+
args = ["/path/to/ytdlp-mcp/src/index.js"]
|
|
7
|
+
[mcp_servers.ytdlp.env]
|
|
8
|
+
YTDLP_DOWNLOAD_DIR = "/path/to/downloads"
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Or let the installer do it:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
node scripts/install.mjs --only=codex
|
|
15
|
+
```
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Cursor (`~/.cursor/mcp.json`) / Copilot CLI (`~/.copilot/mcp-config.json`)
|
|
2
|
+
|
|
3
|
+
```json
|
|
4
|
+
{ "mcpServers": { "ytdlp": {
|
|
5
|
+
"command": "node",
|
|
6
|
+
"args": ["/path/to/ytdlp-mcp/src/index.js"],
|
|
7
|
+
"env": { "YTDLP_DOWNLOAD_DIR": "/path/to/downloads" }
|
|
8
|
+
} } }
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Or let the installer do it:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
node scripts/install.mjs --only=cursor,copilot
|
|
15
|
+
```
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# OpenClaw
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
openclaw mcp add ytdlp --command node --arg /path/to/ytdlp-mcp/src/index.js --env YTDLP_DOWNLOAD_DIR=/path/to/downloads
|
|
5
|
+
openclaw mcp doctor ytdlp --probe
|
|
6
|
+
```
|
|
7
|
+
|
|
8
|
+
Or let the installer do it:
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
node scripts/install.mjs --only=openclaw
|
|
12
|
+
```
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# OpenCode plugin (project or global)
|
|
2
|
+
|
|
3
|
+
Copy the plugin file into your OpenCode plugins directory:
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
# Global
|
|
7
|
+
mkdir -p ~/.config/opencode/plugins
|
|
8
|
+
cp /path/to/ytdlp-mcp/plugin/ytdlp.ts ~/.config/opencode/plugins/
|
|
9
|
+
|
|
10
|
+
# Project-level
|
|
11
|
+
mkdir -p .opencode/plugins
|
|
12
|
+
cp /path/to/ytdlp-mcp/plugin/ytdlp.ts .opencode/plugins/
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Set the repo path so the plugin finds the server:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
export YTDLP_MCP_ENTRY=/path/to/ytdlp-mcp/src/index.js
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or let the installer do it:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
node scripts/install.mjs --only=opencode-plugin
|
|
25
|
+
```
|
package/examples/pi.md
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
# Pi agent (`~/.pi/agent/skills`)
|
|
2
|
+
|
|
3
|
+
Pi reads skills from `~/.pi/agent/skills/`. No MCP server config needed.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
mkdir -p ~/.pi/agent/skills
|
|
7
|
+
ln -s /path/to/ytdlp-mcp/skill ~/.pi/agent/skills/ytdlp-mcp
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
Or let the installer do it:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
node scripts/install.mjs --only=pi
|
|
14
|
+
```
|
package/glama.json
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"$schema":"https://glama.ai/mcp/schemas/server.json","maintainers":["fanyzp"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,64 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fanyzp/ytdlp-mcp",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "An MCP server that enables AI agents to download videos and audio from supported platforms using yt-dlp through natural language instructions.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/fanyzp/ytdlp-mcp.git"
|
|
10
|
+
},
|
|
11
|
+
"keywords": [
|
|
12
|
+
"mcp",
|
|
13
|
+
"model-context-protocol",
|
|
14
|
+
"yt-dlp",
|
|
15
|
+
"youtube",
|
|
16
|
+
"video-downloader",
|
|
17
|
+
"audio",
|
|
18
|
+
"ffmpeg",
|
|
19
|
+
"ai-agent",
|
|
20
|
+
"subtitles",
|
|
21
|
+
"tiktok"
|
|
22
|
+
],
|
|
23
|
+
"bin": {
|
|
24
|
+
"ytdlp-mcp": "./src/index.js"
|
|
25
|
+
},
|
|
26
|
+
"files": [
|
|
27
|
+
"src/",
|
|
28
|
+
"!src/**/*.test.js",
|
|
29
|
+
"scripts/",
|
|
30
|
+
"skill/",
|
|
31
|
+
"examples/",
|
|
32
|
+
"PROMPT.md",
|
|
33
|
+
"README.md",
|
|
34
|
+
"LICENSE",
|
|
35
|
+
"server.json",
|
|
36
|
+
"smithery.yaml",
|
|
37
|
+
"glama.json"
|
|
38
|
+
],
|
|
39
|
+
"scripts": {
|
|
40
|
+
"setup": "node scripts/install.mjs",
|
|
41
|
+
"format": "prettier --write \"src/index.js\" \"src/schemas.js\" \"src/search.js\" \"src/schemas.test.js\" \"src/search.integration.test.js\" \"README.md\" \"package.json\"",
|
|
42
|
+
"format:check": "prettier --check \"src/index.js\" \"src/schemas.js\" \"src/search.js\" \"src/schemas.test.js\" \"src/search.integration.test.js\" \"README.md\" \"package.json\"",
|
|
43
|
+
"test": "node --test"
|
|
44
|
+
},
|
|
45
|
+
"dependencies": {
|
|
46
|
+
"@modelcontextprotocol/sdk": "^1.17.0",
|
|
47
|
+
"zod": "^4.6.6"
|
|
48
|
+
},
|
|
49
|
+
"engines": {
|
|
50
|
+
"node": ">=18"
|
|
51
|
+
},
|
|
52
|
+
"devDependencies": {
|
|
53
|
+
"prettier": "^3.9.10"
|
|
54
|
+
},
|
|
55
|
+
"mcpName": "io.github.fanyzp/ytdlp-mcp",
|
|
56
|
+
"author": "fanyzp",
|
|
57
|
+
"homepage": "https://github.com/fanyzp/ytdlp-mcp#readme",
|
|
58
|
+
"bugs": {
|
|
59
|
+
"url": "https://github.com/fanyzp/ytdlp-mcp/issues"
|
|
60
|
+
},
|
|
61
|
+
"publishConfig": {
|
|
62
|
+
"access": "public"
|
|
63
|
+
}
|
|
64
|
+
}
|