Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@shell-as-mcp install ffmpeg with brew"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π English | δΈζ
TypeScript Shell-as-MCP Server: maps shell commands to standard MCP tools via single-file YAML specs.
Each YAML file defines one MCP tool. The root must contain apiVersion, tool, and execution.
apiVersion: v1
tool:
name: <server>__<action> # snake_case, e.g. brew__install
description: |-
/**
* One-line description of the tool's purpose (TSDoc format, sole description field).
* @param param_name Parameter description
*/
input:
properties:
param_name:
type: string # string | number | integer | boolean
description: "..."
required: [param_name]
output:
type: object
properties:
status: { type: string }
exit_code: { type: number }
stdout: { type: string }
stderr: { type: string }
command: { type: string }
execution_time_ms: { type: number }
execution:
shell:
mode: direct # direct | shell
name: bash # optional: bash | zsh | sh | pwsh | cmd
path: /usr/bin/bash # optional, takes precedence over name
args: ["-lc"] # optional, defaults used if omitted
env:
static:
KEY: VALUE
fromParams:
TOOL_ENV_KEY: inputParamName # UPPER_SNAKE_CASE; add TOOL_ prefix if unsure
fromRuntime:
TARGET_ENV: SOURCE_ENV # maps from server runtime env; supports priority lists
TOOL_OUTPUT_DIR: [YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR]
compatibility:
targets:
- os: macos
kernel: darwin
arch: arm64
support: tested # optional: tested | declared
notes: Apple Silicon only validated target
workingDirectory: /tmp/work
timeoutMs: 30000
taskMode: sync # sync (default, returns result synchronously) | async (background task, returns taskId immediately)
maxOutputBytes: 1048576
# Script mode (recommended: always use this in bundles)
script:
path: ./scripts/<tool_name>.sh # relative to the YAML file's directory
interpreter: bash
# Command mode (only for a single executable + static args; forbid && || ; | > < in args)
# command:
# executable: ffmpeg
# args: ["-version"]Key constraints:
tool.name format is <server>__<action>, all lowercase snake_case
tool.description must be a TSDoc /** */ block comment
execution.env.fromParams env var names use UPPER_SNAKE_CASE; add TOOL_ prefix when clashing with reserved names (PATH, HOME, USER, etc.)
execution.compatibility is optional compatibility metadata; if present, targets must be a non-empty array and each target's os, kernel, arch must be non-empty strings
targets[].support is optional and only allows tested or declared; targets[].notes is optional and must be a string
If a target is marked support: tested, a corresponding per-target smoke test must exist under the bundle's scripts/: {prefix}__smoke_test__{kernel}_{arch}.sh (e.g. brew__smoke_test__darwin_arm64.sh)
execution.command is forbidden when args contain shell operators (&&, ||, ;, |, >, <); multi-step logic must use execution.script
Each YAML defines exactly one tool
execution.env.fromRuntime supports a string array, resolved left-to-right with short-circuit; ideal for expressing group-level to global-level fallback chains
execution.taskMode controls execution mode: sync (default, returns result synchronously) or async (background task, returns taskId immediately; query status via Task management tools)
execution.compatibility.targets declares "known runtime targets", not a "hard platform gate".
Declare each target as a complete tuple to avoid generating incorrect cartesian products by splitting os, kernel, arch into separate lists.
support: tested means the target has actual validation evidence; omitting it or using declared means the target is claimed to work, but the repository does not use this field as a runtime enforcement condition.
The evidence for support: tested is a per-target smoke test script: {prefix}__smoke_test__{kernel}_{arch}.sh; lint verifies its existence.
The current loader and lint validate the field structure, but the server startup and tool exposure logic do not perform platform filtering based on this field.
The __healthz tool's responsibility is dependency availability probing, not business execution.
Goal: quickly determine whether the key runtime dependencies of a command bundle are present and callable.
Output semantics: status=success means dependencies are available; status=error means a dependency is missing or not callable.
Failure boundary: a healthz failure only indicates that the bundle's runtime requirements are not met in the current environment; it must not masquerade as success.
Design requirement: healthz must stay lightweight and idempotent, with no side effects.
For zero-parameter tools (e.g. healthz), the YAML input contract must satisfy:
tool.input must exist and be a mapping (object).
tool.input.properties must exist and be a mapping; empty object is allowed.
tool.input.required should be an empty list for zero-parameter tools.
Introducing dummy parameters just to "pass validation" is not allowed.
Lint alignment rules:
Lint validates the existence and type of tool.input.properties, no longer enforcing non-empty.
This ensures zero-parameter tools are expressed legally and consistently with their runtime behavior.
For the full spec, see shell_as_mcp_defs/runprompt__generate_artifact/prompts/type-specs/shell-as-mcp-yaml.spec.md.
__mcp_response_mode ParameterEvery tool has an implicitly injected optional parameter __mcp_response_mode:
Value | Description |
| Returns result via the MCP |
| Returns result via the MCP |
Typically you do not need to pass this explicitly; the default content mode is sufficient.
Related MCP server: mcp-this
Each subdirectory under shell_as_mcp_defs/ is a command bundle with the following layout:
shell_as_mcp_defs/<server>/
spec_yaml/ # one YAML definition file per tool
scripts/ # one .sh script per tool (referenced by execution.script.path in the YAML)
prompts/ # optional: runprompt prompt templatesManual development workflow:
Create <server>__<action>.yaml under spec_yaml/, following the Β§1 spec
Create the matching .sh under scripts/, reading params via $TOOL_* env vars
Run bash scripts/lint/lint_all.sh to validate
Generating via runprompt__generate_artifact:
β οΈ Work in Progress (WIP): The auto-generation feature of
runprompt__generate_artifactis still under development and not yet stable. The spec documents undertype-specs/can be used directly as a reference for manual development, but relying on this tool to auto-generate bundles in production is not recommended.
runprompt__generate_artifact lets an LLM generate a complete bundle (YAML + scripts + optional prompts) in one shot, with the output automatically written to SHELL_AS_MCP_SPEC_DIR/<server_name>/.
Guidance for LLMs developing a new bundle (AI prompt)
When developing a new
shell_as_mcp_defsbundle:
Full spec is in
shell_as_mcp_defs/runprompt__generate_artifact/prompts/type-specs/:
shell-as-mcp-yaml.spec.mdβ YAML structure and forbidden patterns
script.spec.mdβ corresponding shell script spec
runprompt-prompt.spec.mdβ runprompt prompt specReference existing bundle examples:
brew/,ytdlp/,host_info/,ffmpeg/All tool input params must be mapped to UPPER_SNAKE_CASE env vars via
execution.env.fromParamswithTOOL_prefix; scripts only read$TOOL_*, never$1Validate params early in scripts (fail fast); sensitive operations must be re-authorized inside the script and must not rely on the caller for authorization
execution.commandis only for single-line static commands; multi-step logic must always useexecution.script
All bundles are under
shell_as_mcp_defs/and loaded fromSHELL_AS_MCP_SPEC_DIRat startup.
Tool | Description |
| Probes whether host_info bundle runtime dependencies are available |
| Collects host system context (OS, locale, timezone, hardware, ~35 dev tool versions); ideal as the first call before code execution tasks |
Parameters:
Parameter | Type | Required | Description |
| boolean | No | Whether to include CPU count and memory size; default |
| string | No | Comma-separated tool names (e.g. |
| string | No |
|
Tool | Description | Required Params | Optional Params |
| Probes whether ffmpeg bundle runtime dependencies (ffmpeg/ffprobe) are available | β | β |
| Video preprocessing (trim/scale/fps/speed/strip audio/watermark) |
|
|
| Audio preprocessing (segment/resample/mono/silence removal) |
|
|
| Frame extraction for vision (low fps or keyframes) |
|
|
| Split one video into multiple segments at specified timestamps |
|
|
| Montage summary video (multi-input sampling and concatenation) |
|
|
Currently applies to ffmpeg__extract_frames_for_vision and ffmpeg__split_video.
Priority order:
Explicit parameter output_dir
Group-level env var FFMPEG_OUTPUT_DIR
Global env var SHELL_AS_MCP_OUTPUT_DIR
The tool's "directory output" contract remains unchanged; this only allows the default directory to be sourced from the runtime environment when no explicit parameter is passed.
β οΈ
brew__install/brew__uninstall/brew__upgraderequireconfirm_action=trueto authorize execution; the script will also prompt a native macOS authorization dialog.
Tool | Description | Required Params | Optional Params |
| Probes whether brew bundle runtime dependencies (Homebrew) are available | β | β |
| Query formula/cask details (version, dependencies, homepage) |
|
|
| Search packages |
|
|
| List installed packages | β |
|
| Install a formula/cask |
|
|
| Uninstall a formula/cask |
|
|
| Upgrade a formula/cask |
|
|
The
cookiesparameter accepts a path to a Netscape-format cookies file. You can also runytdlp__setup_cookiesfirst to encrypt and store cookies; subsequent tools will automatically fall back to these stored cookies whencookiesis not specified.
Tool | Description | Required Params | Optional Params |
| Probes whether ytdlp bundle runtime dependencies (yt-dlp) are available | β | β |
| Guides macOS users through exporting cookies via a browser extension and encrypts/saves them (macOS only) | β |
|
| Download video (supports resolution selection and time-range clipping) |
|
|
| Download audio |
|
|
| Download subtitle text content |
|
|
| Download subtitle files |
|
|
| List available subtitle languages for a video |
|
|
| Retrieve full video metadata as JSON |
|
|
| Retrieve video metadata summary (title/duration/channel/etc.) |
|
|
| Retrieve comment list |
|
|
| Retrieve comment summary |
|
|
| Search videos |
|
|
Applies only to ytdlp download tools: ytdlp__download_video, ytdlp__download_audio, ytdlp__download_video_subtitles.
Priority order:
Explicit parameter output_dir
Group-level env var YTDLP_OUTPUT_DIR
Global env var SHELL_AS_MCP_OUTPUT_DIR
Historical default ~/Downloads
Scripts uniformly read TOOL_OUTPUT_DIR; the bundle handles the mapping via execution.env.fromRuntime and execution.env.fromParams. This does not change the existing semantics of output_path / output_dir; it merely adds default value sources for download tools.
Tool | Description | Required Params | Optional Params |
| Probes whether shell bundle base runtime (bash) is available | β | β |
| Runs a local script and echo-prefixes the input value (for development debugging) |
| β |
Advanced SubStation Alpha (ASS) subtitle format toolkit.
Tool | Description | Required Params | Optional Params |
| Probes whether ASS bundle runtime dependencies (ffmpeg) are available | β | β |
| Creates a new ASS v4.00+ subtitle template file (with Default/Title/Note styles) |
|
|
| Returns the ASS format specification document (read-only reference tool) | β |
|
| Validates/lints an ASS subtitle file (16 structural rules) |
|
|
| Renders a test video to verify ASS subtitle renderability (requires ffmpeg) |
|
|
Applies to ass__create_template and ass__smoke_test when output_path is a relative path.
Priority order:
Explicit parameter output_dir
Group-level env var ASS_OUTPUT_DIR
Global env var SHELL_AS_MCP_OUTPUT_DIR
β οΈ Work in Progress (WIP): The auto-generation feature is still under development and not yet stable.
Tool | Description | Required Params | Optional Params |
| Probes whether runprompt bundle runtime prerequisites (python3) are available | β | β |
| Uses runprompt + LLM to auto-generate a complete shell-as-mcp bundle under |
|
|
β οΈ
run_safe_command__executeandrun_safe_command__pipelineboth run without shell eval.executeaccepts a single command + args in a validated working directory;pipelineaccepts a JSON-structured sequence of pipe-connected stages, each validated against a safe command allowlist. On darwin/arm64, both use native Swift+WKWebView for pre-execution authorization and automatically fall back to OSA. All executions are written to a structured audit log.
Tool | Description | Required Params | Optional Params |
| Probes whether run_safe_command runtime dependencies and platform capabilities are available | β | β |
| Executes a command without shell eval; records structured security and audit metadata |
| β |
| Executes a safe shell pipeline from JSON-structured stage definitions; each stage is validated against a command allowlist (no shell eval); async β returns |
| β |
| Shows usage and safety model for the run_safe_command bundle | β |
|
| Reads recent execution audit records | β |
|
| Rotates the audit file and enforces retention | β |
|
iwencai__query2data_basicandiwencai__search_basicare bounded, read-only wrappers around the local iwencai CLI. They requireIWENCAI_API_KEYin the runtime environment and never write output files.
Tool | Description | Required Params | Optional Params |
| Checks whether the local iwencai CLI is available and whether | β | β |
| Runs a bounded natural-language |
|
|
| Runs a bounded search across supported channels: |
|
|
| Exports the built-in iwencai skillbook for local reference or LLM onboarding | β |
|
npm install
npm run build
npm startnpx -y github:meomeo-dev/shell-as-mcp --transport stdioIf you use the runprompt__generate_artifact tool, install runprompt separately:
# Using uv (recommended)
uv pip install git+https://github.com/chr15m/runprompt
# Using pip
pip install "git+https://github.com/chr15m/runprompt.git"Option | Env Var | Default | Description |
|
|
|
|
|
|
| YAML spec directory (overlay) |
|
|
| HTTP listen address |
|
|
| HTTP listen port |
|
|
| HTTP path |
|
| β (unlimited) | Max concurrent background async tasks |
β |
|
| MCP server name |
β |
|
| MCP server version |
The tools in the built-in shell_as_mcp_defs/ are always loaded directly from the package. SHELL_AS_MCP_SPEC_DIR is an overlay directory that additionally loads tools from it; tools with the same name as built-in ones are overridden by the user directory.
The default value is ./shell_as_mcp_defs (loaded only once when it matches the built-in path).
{
"mcpServers": {
"shell-as-mcp": {
"command": "npx",
"args": ["-y", "github:meomeo-dev/shell-as-mcp", "--transport", "stdio"],
"env": {
"SHELL_AS_MCP_SPEC_DIR": "/absolute/path/to/specs",
"RUNPROMPT_MODEL": "openrouter/deepseek/deepseek-v3.2",
"RUNPROMPT_BASE_URL": "https://openrouter.ai/api/v1",
"RUNPROMPT_OPENROUTER_API_KEY": "sk-or-v1-xxxx",
"https_proxy": "http://127.0.0.1:8890",
"HTTPS_PROXY": "http://127.0.0.1:8890"
}
}
}
}{
"mcpServers": {
"shell-as-mcp-http": {
"command": "npx",
"args": [
"-y", "github:meomeo-dev/shell-as-mcp",
"--transport", "streamable-http",
"--host", "127.0.0.1",
"--port", "3001",
"--http-path", "/mcp"
],
"env": {
"SHELL_AS_MCP_SPEC_DIR": "/absolute/path/to/specs",
"SHELL_AS_MCP_SERVER_NAME": "shell-as-mcp-http"
}
}
}
}All of the following env vars can be placed directly in mcpServers.<name>.env.
Env Var | Purpose | Default |
| Transport mode: |
|
| Overlay spec directory |
|
| HTTP listen address |
|
| HTTP listen port |
|
| HTTP path |
|
| MCP server name |
|
| MCP server version |
|
| Max concurrent background async tasks | β (unlimited) |
Env Var | Purpose | Applicable Tools |
| Global output directory fallback |
|
| ytdlp group-level output directory |
|
| ffmpeg group-level output directory |
|
| ASS group-level output directory |
|
Env Var | Purpose | Fallback |
| LLM model name |
|
| API Base URL |
|
| API Key |
|
| Print the full rendered prompt and enable verbose debug before the request | β |
| Output runprompt startup diagnostics | β |
| Timeout in seconds for the runprompt Python layer |
|
| Root directory for runprompt file tools | Rarely needs manual configuration |
Env Var | Purpose | Applicable Tools |
| API key passed through to the local iwencai CLI for bounded read-only queries |
|
Env Var | Purpose |
| Lowercase HTTPS proxy env var |
| Uppercase HTTPS proxy env var |
In short: if you just run the server normally, you typically only need SHELL_AS_MCP_SPEC_DIR; if you need file output, also add SHELL_AS_MCP_OUTPUT_DIR or the group-level directory vars; if you use runprompt__generate_artifact, also supply the RUNPROMPT_* vars.
runprompt__generate_artifact environment variables (β οΈ auto-generation is WIP):
Var | Description | Fallback |
| LLM model name |
|
| API Base URL |
|
| API Key |
|
Debug tip: set RUNPROMPT_DEBUG_PROMPT=1 to print the full rendered prompt before the request and enable runprompt -v.
# All TypeScript tests (unit + contract + e2e)
npm test
# Run smoke tests (generic + current-target)
bash scripts/run_smoke_tests.sh
# Build + pack + strict protocol handshake smoke in one command
make regress-pack-smoke
# Lint (YAML spec + shellcheck + prompt format; full scan of shell_as_mcp_defs/)
bash scripts/lint/lint_all.shlint_all.sh auto-discovers and validates five categories:
spec_yaml/*.yaml β validate_shell_as_mcp_yaml.sh (structure/fields/forbidden patterns)
scripts/*.sh β validate_script.sh (shellcheck)
prompts/*.prompt (not starting with _) β validate_runprompt_prompt.sh (frontmatter/schema)
spec_yaml/*.yaml (containing support: tested) β validate_tested_has_smoke_test.sh (verifies the corresponding per-target smoke test exists)
SKILL.md β validate_skill_md.sh (frontmatter and structure)
run_smoke_tests.sh first runs each bundle's generic smoke test (*__smoke_test.sh), then auto-discovers and runs the per-target smoke test matching the current platform (e.g. *__smoke_test__darwin_arm64.sh).
make regress-pack-smoke runs build, npm pack, starts the server in streamable-http mode from the tarball, and validates the strict handshake sequence: initialize, notifications/initialized, tools/list.
Single-file validation:
bash scripts/lint/validate_shell_as_mcp_yaml.sh shell_as_mcp_defs/brew/spec_yaml/brew__info.yaml
bash scripts/lint/validate_script.sh shell_as_mcp_defs/brew/scripts/brew__info.sh
bash scripts/lint/validate_tested_has_smoke_test.sh shell_as_mcp_defs/brew/spec_yaml/brew__info.yamlmake build # clean + compile TypeScript + copy runtime assets
make test # equivalent to npm test (unit + e2e)
make lint # equivalent to bash scripts/lint/lint_all.sh
make deps # npm ci to install dependencies
make help # show all available make targets# Build image
make docker-build
# Run container (stdio mode)
make docker-run
# Enter container shell for debugging
make docker-shellThis project builds on top of the following excellent open-source projects:
@modelcontextprotocol/sdk β TypeScript MCP SDK providing standardized MCP server protocol implementation
runprompt β CLI LLM prompt runner powering the runprompt__generate_artifact bundle
dotprompt β Google's structured prompt format specification, influencing this project's prompt template design
MIT β see LICENSE for details.
Create a new ASS subtitle template file with Default, Title, and Note styles. @remarks Writes a valid ASS v4.00+ file with pre-configured styles for general subtitles, title overlays, and note text. Fails if the output file already exists unless overwrite=true. @param output_path Destination path for the generated .ass file. @param output_dir Optional output directory fallback for relative output_path. Falls back to ASS_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param title Script title embedded in [Script Info] section. Default: "Untitled". @param play_res_x Virtual canvas width in pixels. Default: 1920. @param play_res_y Virtual canvas height in pixels. Default: 1080. @param overwrite If true, overwrite the file when it already exists. Default: false. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: output_path (required), title, overwrite, output_dir, +3 more.
Returns the ASS (Advanced SubStation Alpha) subtitle format specification. @remarks Read-only reference tool. Returns structured spec content for the requested section. No external files or network access required; content is fully embedded in the script. @param section Which section of the ASS spec to return. Default "all". Allowed values: all | script_info | v4_styles | events | tags | colors | example @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: section, __mcp_response_mode.
Check whether the ASS tool bundle runtime dependencies are available. @remarks Validates ffmpeg presence and returns a small JSON health report. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
Lint and validate an ASS (Advanced SubStation Alpha) subtitle file. @remarks Checks 16 structural rules including section headers, ScriptType, PlayRes fields, Format/Style/Dialogue line presence, time format validity, and color field format. Returns a JSON report with per-check results. In strict mode, also validates field counts per Dialogue (>=10) and Style (=23). @param ass_file_path Absolute or relative path to the .ass file to lint. @param strict When true, enables additional field-count checks (checks 15 & 16). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: ass_file_path (required), strict, __mcp_response_mode.
Render a short test video from an ASS subtitle file to verify renderability. @remarks Uses ffmpeg lavfi virtual color source to generate a background, then overlays the ASS subtitles via the subtitles filter (requires libass support in ffmpeg). Outputs a JSON summary on success or an error payload on failure. @param ass_file_path Path to the ASS subtitle file to render. @param output_path Path for the output MP4 video file. @param output_dir Optional output directory fallback for relative output_path. Falls back to ASS_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param duration_sec Duration of the test video in seconds (1-300). Default: 10. @param resolution Output video resolution in WxH format. Default: 1920x1080. @param background_color Background color for the test video (ffmpeg color name or hex). Default: black. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: output_path (required), ass_file_path (required), output_dir, resolution, +3 more.
Cancel a running background task. Sends SIGTERM followed by SIGKILL if needed.
Inputs: taskId (required).
Remove completed, failed, or cancelled tasks from memory. Optionally specify maxAgeMs to only remove tasks older than the given milliseconds.
Inputs: maxAgeMs.
Get full details of a background task by taskId, including stdout/stderr output.
Inputs: taskId (required).
List all background tasks. Optionally filter by status.
Inputs: status.
Add fade-in and/or fade-out transitions to a video clip. @remarks At least one of fade_in_duration or fade_out_duration must be greater than zero. Audio fade is applied simultaneously when include_audio is true. Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param output_path Destination video path with fade transitions. @param fade_in_duration Fade-in duration in seconds. Default 0 (no fade in). @param fade_out_duration Fade-out duration in seconds. Default 0 (no fade out). @param fade_color Fade transition color: black or white. Default black. @param include_audio Whether to apply afade filter synchronously with the video fade. Default true. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), fade_color, include_audio, +3 more.
Apply a .cube format 3D color Look-Up Table (LUT) to a video for color grading. @remarks Uses the ffmpeg lut3d filter. Returns JSON in stdout with output_path and lut_path. @param input_path Source video path. @param lut_path Path to a .cube format LUT file. @param output_path Destination color-graded video path. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: lut_path (required), input_path (required), output_path (required), __mcp_response_mode.
Hard-burn SRT or ASS subtitle file into a video using the ffmpeg subtitles filter. @remarks Consumes .ass files produced by the ass bundle (ass__create_template). Re-encodes the video track. Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param subtitle_path Subtitle file path (.srt or .ass). @param output_path Destination video path with burned-in subtitles. @param force_style Optional ASS/SSA style override string (for example Fontsize=24,PrimaryColour=&HFFFFFF&). Applies to both SRT and ASS inputs. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), subtitle_path (required), force_style, +1 more.
Concatenate multiple video clips in sequence using the ffmpeg concat demuxer. @remarks input_paths accepts a comma or newline-separated list of clip paths. Returns JSON in stdout with output_path and clip_count. Use reencode=true when clips have different codecs or parameters. @param input_paths Comma or newline-separated list of clip file paths in playback order. @param output_path Destination video path. @param reencode Whether to re-encode during concat (required for clips with different codecs), default false. @param video_codec Video codec when re-encoding, default libx264. @param audio_codec Audio codec when re-encoding, default aac. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_paths (required), output_path (required), reencode, audio_codec, +2 more.
Create a montage-style summary clip from one or more videos. @remarks input_paths accepts one path or a comma/newline-separated list. Returns JSON in stdout with output_path and sampled clip_count. @param input_paths One path or a comma/newline-separated list of source video paths. @param output_path Destination summary video path. @param interval_sec Sampling interval in seconds, default 300. @param clip_duration_sec Duration of each sampled clip in seconds, default 2. @param merge_audio Whether to keep audio in sampled clips, default true. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_paths (required), output_path (required), merge_audio, interval_sec, +2 more.
Transcode a video to a delivery-grade output with full codec and quality control. @remarks Supports H.264, H.265, and VP9. Use crf for quality-based encoding or bitrate for target-bitrate mode (mutually exclusive; bitrate takes precedence). Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param output_path Destination video path. @param video_codec Output video codec: libx264, libx265, or libvpx-vp9. Default libx264. @param crf Constant Rate Factor for quality-based encoding. Default 23 for H.264, 28 for H.265, 33 for VP9. @param bitrate Target video bitrate (for example 4M). Overrides crf when set. @param preset Encoding speed/compression preset. Default medium. @param profile H.264/H.265 profile (for example baseline, main, high). @param level H.264/H.265 level (for example 4.0, 4.1). @param resolution Output resolution as WxH (for example 1920x1080). Keeps original if omitted. @param audio_bitrate Output audio bitrate. Default 128k. @param pixel_format Output pixel format. Default yuv420p. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), crf, level, +8 more.
Extract image frames for multimodal vision prompts. @remarks Returns JSON in stdout with frame_paths and frame_count for direct LLM/prompt ingestion. @param input_path Source video path. @param output_dir Optional output directory. Falls back to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param start_time Optional start timestamp. @param end_time Optional end timestamp. @param fps Optional extraction fps (for example 0.5 for one frame every two seconds). @param keyframes_only Whether to extract only keyframes (I-frames). @param max_resolution Optional longest-edge cap for generated frames. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), fps, end_time, output_dir, +4 more.
Transcode high-bitrate source footage to an edit-friendly H.264 proxy. @remarks Generates a lower-bitrate proxy suitable for editing. Returns JSON in stdout with output_path and applied parameters. @param input_path Source video path. @param output_path Destination proxy video path. @param width Proxy output width in pixels. Height is auto-calculated to maintain aspect ratio. Default 1280. @param crf H.264 CRF quality factor (lower = better quality). Default 28. @param fps Optional output frame rate to unify mixed-fps footage. @param pixel_format Output pixel format. Default yuv420p for maximum compatibility. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), crf, fps, +3 more.
Extract a single frame from a video at a specified timestamp to use as a thumbnail or poster image. @remarks Returns JSON in stdout with output_path and applied parameters. Output format is determined by output_path extension (jpg recommended). @param input_path Source video path. @param output_path Destination image path (for example thumbnail.jpg or poster.png). @param timestamp Timestamp to extract the frame from. Default 00:00:01. @param width Output image width in pixels. Height is auto-calculated. Default 1280. @param quality JPEG quality factor 1-31 (lower value = better quality). Default 2. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), width, quality, +2 more.
Check whether ffmpeg runtime dependency is available. @remarks Returns ffmpeg version and health status as JSON. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
Mix two audio tracks (voice and background music) into a single output using the amix filter. @remarks Typical use: normalize voice first, then mix with BGM using a low bgm_volume (0.2β0.3). Returns JSON in stdout with output_path and applied volume parameters. @param voice_path Primary audio track path (for example voice or narration). @param bgm_path Background music track path. @param output_path Destination mixed audio path. @param voice_volume Volume multiplier for the primary track. Default 1.0. @param bgm_volume Volume multiplier for the background music track. Default 0.3. @param duration Output duration strategy: shortest (default), longest, or first. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: bgm_path (required), voice_path (required), output_path (required), duration, +3 more.
Replace or attach an audio track to a video by muxing a separate audio file. @remarks The original video audio is discarded. Typical use: attach a mixed or dubbed audio track to a graded video. Returns JSON in stdout with output_path and applied parameters. @param video_path Source video path (its original audio track will be discarded). @param audio_path Replacement audio track path. @param output_path Destination video path with the new audio track. @param audio_delay_ms Audio track delay in milliseconds (positive = delay audio). Default 0. @param reencode_audio Whether to re-encode the audio to AAC. Default false uses stream copy. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: audio_path (required), video_path (required), output_path (required), audio_delay_ms, +2 more.
Normalize audio loudness to a target EBU R128 LUFS using the ffmpeg loudnorm filter. @remarks Returns JSON in stdout with output_path and applied normalization parameters. Default target of -14 LUFS is suitable for most streaming platforms (YouTube, Spotify). @param input_path Source audio or video path. @param output_path Destination audio path. @param target_lufs Target integrated loudness in LUFS. Default -14. @param true_peak Maximum true peak level in dBTP. Default -1.0. @param loudness_range Target loudness range (LRA) in LU. Default 11. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), true_peak, target_lufs, +2 more.
Probe a media file and return full metadata as JSON using ffprobe. @remarks Returns ffprobe JSON output in stdout with streams and format information. @param input_path Source media file path (video or audio). @param stream_type Filter streams to probe: all (default), video, or audio. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), stream_type, __mcp_response_mode.
Build a Whisper/STT-ready compact audio output from either audio or video input. @remarks Returns a JSON summary in stdout with output_path and normalization parameters for LLM-friendly parsing. @param input_path Source media path (video or audio). @param output_path Destination audio path. @param start_time Optional start timestamp (for example 00:04:30). @param end_time Optional end timestamp (for example 00:05:30). @param sample_rate Output sample rate in Hz, default 16000. @param channels Output channels count, default 1. @param remove_silence Whether to remove long silent regions, default true. @param audio_format Output container format, default mp3. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), channels, end_time, +5 more.
Build an LLM-ready video in one ffmpeg run (trim, scale, fps, speed, optional audio strip and watermark). @remarks Returns a compact JSON summary in stdout with output_path and applied options for LLM-friendly parsing. @param input_path Source video path. @param output_path Destination video path. @param start_time Optional start timestamp (for example 00:04:30). @param end_time Optional end timestamp (for example 00:05:30). @param max_resolution Optional longest-edge cap (for example 720). @param fps Optional output fps (for example 1.0). @param speed_factor Playback speed factor (for example 2.0). @param strip_audio Whether to remove audio track. @param watermark_path Optional watermark/subtitle image path. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), output_path (required), fps, end_time, +6 more.
Split a single video into multiple segments at specified timestamps. @remarks split_points is a comma-separated list of timestamps (HH:MM:SS or seconds). Returns JSON in stdout with output_dir, segment_count, and segments array. Falls back to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR if output_dir param is omitted. @param input_path Source video file path. @param output_dir Output directory for generated segments. Falls back to FFMPEG_OUTPUT_DIR or SHELL_AS_MCP_OUTPUT_DIR. @param split_points Comma-separated list of cut timestamps, for example 00:10:00,00:20:00,00:30:00. @param output_prefix Filename prefix for segment files, default segment. @param reencode Whether to re-encode segments. Default false uses stream copy (faster but may cause keyframe misalignment). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: input_path (required), split_points (required), reencode, output_dir, +2 more.
Collect host system context for code development tasks in a single call. @remarks Returns two sections: 'system' (OS, locale, timezone, hardware, current time) and 'dev_environments' (availability, path, and version for ~35 programming tools). Ideal as a first call before writing or running code on the host. @param include_hardware Whether to include CPU count and total memory size in system section. Default true. @param filter_tools Optional comma-separated list of tool names to probe (e.g. 'python3,node,rustc'). Empty = check all ~35 tools. @param output_format JSON indentation style: 'pretty' (default, 2-space indent) or 'compact'. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: filter_tools, output_format, include_hardware, __mcp_response_mode.
Check whether host_info bundle can access basic host context commands. @remarks Verifies uname availability and emits a compact JSON report. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
Generate a shell-as-mcp bundle with runprompt under SHELL_AS_MCP_SPEC_DIR. @param artifact_type Artifact type: shell-as-mcp-bundle. @param requirements Natural language requirements used to generate file content. @param server_name Optional server folder for shell-as-mcp-bundle mode. @param tool_name Optional tool base name for shell-as-mcp-bundle mode. @param max_repair_rounds Optional max repair rounds when quality gates fail. @param run_tests Optional toggle for running tests in quality gates. @param run_code_review Optional toggle for running code review gate (default true). @param run_security_review Optional toggle for running security review gate (default true). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: requirements (required), artifact_type (required), run_tests, tool_name, +5 more.
Check whether runprompt bundle runtime prerequisites are available. @remarks Verifies python3 availability and returns version in JSON. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
Read recent run_safe_command execution audit records. @param limit Maximum number of most recent entries to return. Default 20. @param include_rotated Include rotated audit files in addition to the active audit file. Default true. @param rotated_file_limit Maximum number of rotated audit files to scan. Range 1-50. Default 10. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: limit, include_rotated, rotated_file_limit, __mcp_response_mode.
Rotate run_safe_command audit file immediately and enforce retention. @param max_files Optional retention count for rotated files. Range 1-100. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: max_files, __mcp_response_mode.
Execute a command safely with structured security and audit metadata. @remarks The command is executed without shell eval in a validated working directory. Runtime control behaviors are internal-only and not caller-configurable. On darwin/arm64, pre-execution auth prefers native Swift+WKWebView and automatically falls back to OSA. @param command Executable name to run (for example: ls, cat, grep). @param args_json JSON array string of positional arguments, for example ["-la", "./src"]. @param working_dir Absolute working directory where the command will run. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: command (required), args_json (required), working_dir (required), __mcp_response_mode.
Check run_safe_command runtime dependencies and platform capabilities. @remarks Missing optional trace tools (for example strace on macOS) are reported as warnings, not hard failures. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
Show usage and safety model for run_safe_command tools. @param topic Optional topic filter: execute, audit, healthz, security. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: topic, __mcp_response_mode.
Execute a safe shell pipeline from structured stage definitions. @remarks Each stage is validated against a command allowlist before execution. The pipeline is assembled using Python subprocess chaining (Popen stdin chains), not via shell eval or bash -c with user-supplied data. Commands are restricted to a safe processing-only allowlist; destructive or network commands are not permitted. Unlike run_safe_command__execute, this tool accepts pipe-connected stage sequences but applies stricter per-stage command validation to compensate. On darwin/arm64, pre-execution auth prefers native Swift+WKWebView and automatically falls back to OSA. @param stages_json JSON array of pipeline stage objects. Each stage must have "command" (string) and "args" (string array). Commands must pass the pipeline allowlist: grep, awk, sed, cut, sort, uniq, wc, head, tail, cat, echo, tr, xargs, find, ls, ps, du, df, date, env, printenv, uname, hostname, id, whoami, pwd, dirname, basename. Example: [{"command":"ps","args":["aux"]},{"command":"grep","args":["python"]}] @param working_dir Absolute working directory shared by all pipeline stages. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: stages_json (required), working_dir (required), __mcp_response_mode.
Check whether shell bundle basic runtime is available. @remarks Verifies bash command presence and returns JSON status. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
Run a local script and echo the input value with prefix. @param value Input value passed to the script. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: value (required), __mcp_response_mode.
Download audio from a video URL using yt-dlp, saving as m4a to output_dir or a configured default directory. @remarks Extracts best-quality audio track. Supports optional cookies file and proxy. @param url The video URL to download audio from (must start with http:// or https://). @param output_dir Optional output directory. Falls back to YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, or ~/Downloads. @param cookies Optional path to a Netscape-format cookies file for authenticated downloads. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, maxRetries, +2 more.
Download and extract plain-text transcript from a video URL using yt-dlp. @remarks Downloads VTT subtitles (manual or auto-generated) to a temp dir, converts to plain text (strips timestamps, NOTE blocks, duplicate adjacent lines), then cleans up. @param url The video URL (must start with http:// or https://). @param language Subtitle language code. Defaults to "en". @param output_dir Optional output directory. If set, transcript text is also saved as a .txt file. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, language, +3 more.
Download a video from a URL using yt-dlp, saving to output_dir or a configured default directory. @remarks Supports resolution selection and optional time-range trimming via --download-sections. Both startTime and endTime must be provided together to enable trimming. @param url The video URL (must start with http:// or https://). @param resolution Target resolution: "480p", "720p" (default), "1080p", or "best". @param startTime Optional start time for clip extraction (e.g. "00:01:30"). @param endTime Optional end time for clip extraction (e.g. "00:05:00"). @param output_dir Optional output directory. Falls back to YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, or ~/Downloads. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, endTime, +5 more.
Download subtitle files (VTT) for a video URL using yt-dlp, saving to output_dir or a configured default directory. @remarks Downloads both manual and auto-generated subtitles without downloading the video itself. @param url The video URL (must start with http:// or https://). @param language Subtitle language code. Defaults to "en". @param output_dir Optional output directory. Falls back to YTDLP_OUTPUT_DIR, SHELL_AS_MCP_OUTPUT_DIR, or ~/Downloads. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, language, +3 more.
Fetch video comments from a URL using yt-dlp and return structured JSON. @remarks Uses yt-dlp --write-comments -j to extract comments metadata, then filters/sorts via Python to return at most maxComments entries. @param url The video URL (must start with http:// or https://). @param maxComments Maximum number of comments to return (1-5000). Defaults to 100. @param sortOrder Comment sort order: "top" (default) or "new". @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address. @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, sortOrder, +3 more.
Fetch and summarize top comments from a video URL using yt-dlp. @remarks Returns formatted comment list with author, like count, and text. @param url The video URL (must start with http:// or https://). @param maxComments Number of comments to return (1-50, default 10). @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, maxRetries, +2 more.
Fetch raw metadata JSON for a video URL using yt-dlp. @remarks Returns full or filtered metadata fields as JSON. @param url The video URL (must start with http:// or https://). @param fields Comma-separated field names to return (e.g. "title,uploader,view_count"); empty returns all. @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, fields, cookies, +2 more.
Fetch and display a human-readable metadata summary for a video URL using yt-dlp. @remarks Returns title, channel, duration, upload date, views, likes, tags, and description snippet. @param url The video URL (must start with http:// or https://). @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, maxRetries, +1 more.
Check whether ytdlp bundle runtime dependency is available. @remarks Verifies yt-dlp, python3, node and _ytdlp_cookies_lib.sh availability, then returns yt-dlp version in JSON. @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: __mcp_response_mode.
List all available subtitle languages for a video URL using yt-dlp. @remarks Outputs subtitle language codes and formats without downloading. @param url The video URL (must start with http:// or https://). @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: url (required), proxy, cookies, maxRetries, +1 more.
Search YouTube videos by keyword using yt-dlp and return results as summary or JSON. @remarks Uses ytsearch to query YouTube; supports pagination via offset and date filtering. @param query Search keywords (must not contain newlines). @param maxResults Number of results to return (1-50, default 10). @param offset Pagination offset (default 0). @param response_format Output format: "summary" (default) or "json". @param uploadDateFilter Filter by upload date: "today", "week", "month", or "year". @param cookies Optional path to a Netscape-format cookies file. @param proxy Optional proxy address (e.g. socks5://127.0.0.1:1080). @param maxRetries Optional retry count after failures, capped at 2 (default: 2). @param __mcp_response_mode Optional response mode: content (default) or structuredContent.
Inputs: query (required), proxy, offset, cookies, +5 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
Scored across 49 tools
Multiple healthz tools across bundles (ffmpeg__healthz, ass__healthz, shell__healthz, etc.) are functionally identical, and several ffmpeg transcode tools (export_video, generate_proxy, process_video_for_llm) have overlapping parameters and purposes. The ytdlp summary/full pairs add further ambiguity.
Tool names consistently follow a bundle__verb_noun pattern with snake_case, and the bundle prefix provides a clear namespace. Minor deviations exist (e.g., ffmpeg__extract_frames_for_vision vs. simple verb_noun names), but the overall pattern is predictable.
49 tools is excessive for a coherent server; it aggregates multiple independent domains (ffmpeg, yt-dlp, ASS, safe command, host info) into one namespace. The high count is inflated by redundant healthz checks and trivial wrappers, making selection and navigation burdensome.
Major subdomains like ffmpeg and yt-dlp have decent coverage, but the shell bundle is nearly empty (only a trivial echo script), and there are notable gaps such as no simple audio extraction tool and no unified status/diagnostics tool. The broad scope makes full completeness difficult to assess.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Generate a typed SDK, CLI, and MCP server from any OpenAPI or GraphQL spec, and keep them current.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for progressive tool usage at any scale (see https://klavis.ai)