Convertrilo

io.github.serkandrgnPublished by GitHub account serkandrgnv0.1.2Updated Oct 24, 2026

Create and manage Convertrilo video encoding jobs from MCP clients and agent workflows.

VerifiedSTDIODesktop onlyCloud & Infrastructure Files & Storage Media & Design

Server details

Identifier: io.github.serkandrgn/convertrilo
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account serkandrgn for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.serkandrgn%2Fconvertrilo.svg)](https://sourceweft.com/mcp/io.github.serkandrgn%2Fconvertrilo?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Lets an assistant create and manage Convertrilo cloud video encoding jobs, including status checks, cancellation, and output delivery.

What you can do: Convertrilo exposes a stdio MCP server (convertrilo-mcp) alongside a CLI and TypeScript SDK for the Convertrilo video encoding API. It lets an assistant submit encode jobs from a source URL, S3, or Google Drive, choose codec, resolution, quality, audio and frame-rate policies, and poll job status until completion. It also covers bulk folder ingest, saved encode presets, saved output destinations, job cancellation, file cleanup, and webhook delivery history.
When to use it: Use it when an agent or workflow needs to transcode video without building its own encoding pipeline, for example compressing uploads, producing 1080p web MP4s, or queuing one job per video in a storage folder. It suits server-side automation rather than browser apps.
Requirements: Runs as a local Node.js process via the npm package @convertrilo/sdk, which targets modern Node.js runtimes with global fetch. A Convertrilo API key is needed, supplied as the CONVERTRILO_API_KEY environment variable or saved locally with convertrilo login or convertrilo init. S3 or Google Drive output requires customer-owned storage credentials or a service account.

Before you install

Encoding is billed, and pricing responses expose requestedPasses and effectivePasses, so job volume and pass settings affect cost. The API key and any customer storage credentials, such as CUSTOMER_S3_ACCESS_KEY_ID, CUSTOMER_S3_SECRET_ACCESS_KEY, or GOOGLE_SERVICE_ACCOUNT_JSON, must stay server-side and never in frontend code. Jobs write output to your storage, and deleteJobFiles removes managed upload and output objects, so cancel active jobs first.

Installation

In SourceWeft

Open Convertrilo in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Convertrilo TypeScript SDK

Type-safe client for the Convertrilo API.

VMAF And Encoding Passes

When optimize: "vmaf" is requested, Convertrilo performs VMAF sampling and one optimized final encode. A supplied passes: 2 value remains accepted for backward compatibility, but the API uses and bills one effective pass.

Pricing responses expose requestedPasses and effectivePasses. New integrations should use passes: 1 with VMAF.

Install

The package currently targets modern Node.js runtimes with global fetch. If your runtime does not provide fetch, pass fetchImpl to the client.

CLI And MCP Automation

The package includes two executable automation tools:

bash

export CONVERTRILO_API_KEY="cvr_..."
convertrilo encode https://example.com/input.mp4 \  --codec h264 \  --resolution 1080p \  --audio-policy transcode-aac \  --frame-rate-policy cap \  --scale-policy no-upscale \  --quality better \  --wait \  --json
convertrilo-mcp

export CONVERTRILO_API_KEY="cvr_..."
convertrilo encode https://example.com/input.mp4 \  --codec h264 \  --resolution 1080p \  --audio-policy transcode-aac \  --frame-rate-policy cap \  --scale-policy no-upscale \  --quality better \  --wait \  --json
convertrilo-mcp

Use convertrilo for scripts, CI, cron, and local operations. Use convertrilo-mcp as a stdio MCP server for agent and workflow integrations.

Run convertrilo login or convertrilo init to save an API key locally, or run convertrilo with no arguments to start the interactive encode wizard. Waiting commands show terminal progress by default and keep --json clean for scripts.

Shell completion snippets are available with:

See docs/CLI-AND-MCP.md for commands, MCP client config, S3 output examples, VMAF, two-pass, status, cancel, and balance workflows.

If you want the simplest terminal walkthrough, start with docs/CLI-QUICKSTART.md.

For agent/client setup, use docs/MCP-QUICKSTART.md.

MCP registry metadata lives in server.json.

Create A Client

import { ConvertriloClient } from "@convertrilo/sdk";
const client = new ConvertriloClient({  baseUrl: "https://api.convertrilo.com",  apiKey: process.env.CONVERTRILO_API_KEY,});

import { ConvertriloClient } from "@convertrilo/sdk";
const client = new ConvertriloClient({  baseUrl: "https://api.convertrilo.com",  apiKey: process.env.CONVERTRILO_API_KEY,});

Use an API key for server-to-server integrations. Browser apps should call your own backend, then your backend calls Convertrilo.

Examples

The examples/ directory contains starter scripts for the main integration paths:

node-url-to-cdn.ts - encode a public URL and receive a signed CDN download URL
node-url-to-s3.ts - encode a public URL and upload the result to S3/S3-compatible storage
google-drive-byo-token.ts - upload output to Google Drive using a customer-owned service account
folder-ingest-s3.ts - queue one encode job per video in an S3 prefix
idempotency.ts - safely retry createJob and createJobsBulk
webhook-receiver-hmac.ts - verify managed webhook HMAC signatures from a Node receiver

Local SDK smoke tests use .env, but published SDK users should provide credentials through their own server environment. Do not put Convertrilo API keys or customer storage tokens in frontend code.

For a complete server-to-server walkthrough covering URL, S3, folder ingest, Google Drive service accounts, polling, and webhooks, see docs/API-INTEGRATION-GUIDE.md.

Idempotent Job Creation

Use an idempotency key when retrying create calls from your backend. Reusing the same key with the same body returns the original response instead of creating duplicate jobs.

const job = await client.createJob({  externalId: "upload-123",  metadata: { customerId: "cus_123" },  codec: "h264",  resolution: "1080p",  fps: 30,}, {  idempotencyKey: "job-upload-123",});
const batch = await client.createJobsBulk({  jobs: [    {      externalId: "batch-42:clip-1",      codec: "h264",      resolution: "1080p",      fps: 30,      sourceS3: { bucket: "source", key: "clip-1.mp4" },    },  ],  settings: { confirm: true },}, {  idempotencyKey: "bulk-batch-42",});

const job = await client.createJob({  externalId: "upload-123",  metadata: { customerId: "cus_123" },  codec: "h264",  resolution: "1080p",  fps: 30,}, {  idempotencyKey: "job-upload-123",});
const batch = await client.createJobsBulk({  jobs: [    {      externalId: "batch-42:clip-1",      codec: "h264",      resolution: "1080p",      fps: 30,      sourceS3: { bucket: "source", key: "clip-1.mp4" },    },  ],  settings: { confirm: true },}, {  idempotencyKey: "bulk-batch-42",});

Job File Cleanup

Delete managed upload and output objects after a job reaches a terminal state:

await client.cancelJob(jobId); // required first for created, queued, or running jobs
const result = await client.deleteJobFiles(jobId);console.log(result.objectsDeleted, result.jobRetained);

await client.cancelJob(jobId); // required first for created, queued, or running jobs
const result = await client.deleteJobFiles(jobId);console.log(result.objectsDeleted, result.jobRetained);

The job record and billing history remain available for auditing. Active jobs return the stable job_active error until they are canceled.

Saved Encode Presets

Save reusable encode settings without storing source URLs, storage credentials, or output secrets:

const preset = await client.createEncodePreset({  name: "Default 1080p web MP4",  settings: {    codec: "h264",    resolution: "1080p",    fps: 30,    preset: "standard",    bitrateTier: "medium",    passes: 1,    policy: "fastest",    container: "mp4",    quality: "better",    optimize: "none",    vmafTarget: 93,    audioPolicy: "transcode-aac",    frameRatePolicy: "cap",    scalePolicy: "no-upscale",  },});
const { presets } = await client.getEncodePresets();

const preset = await client.createEncodePreset({  name: "Default 1080p web MP4",  settings: {    codec: "h264",    resolution: "1080p",    fps: 30,    preset: "standard",    bitrateTier: "medium",    passes: 1,    policy: "fastest",    container: "mp4",    quality: "better",    optimize: "none",    vmafTarget: 93,    audioPolicy: "transcode-aac",    frameRatePolicy: "cap",    scalePolicy: "no-upscale",  },});
const { presets } = await client.getEncodePresets();

Saved Output Destinations

Save reusable delivery targets without storing raw storage secrets in the destination itself. S3 destinations reference an encrypted saved S3 credential:

const destination = await client.createOutputDestination({  name: "Customer uploads bucket",  config: {    type: "s3",    credentialId: "0f5a7f2b-4ff2-45d4-b76f-1f7b6e98d4d1",    keyPrefix: "processed/",  },});
const { destinations } = await client.getOutputDestinations();

const destination = await client.createOutputDestination({  name: "Customer uploads bucket",  config: {    type: "s3",    credentialId: "0f5a7f2b-4ff2-45d4-b76f-1f7b6e98d4d1",    keyPrefix: "processed/",  },});
const { destinations } = await client.getOutputDestinations();

URL Source To CDN Output

const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  externalId: "customer-video-123",  metadata: {    customerId: "cus_123",    workflow: "daily-compression",  },  codec: "h264",  resolution: "1080p",  quality: "better",  audioPolicy: "transcode-aac",  frameRatePolicy: "cap",  scalePolicy: "no-upscale",}, {  idempotencyKey: "encode-customer-video-123",});
let finalStatus;while (true) {  finalStatus = await client.onDemandStatus(job.jobId);
  if (finalStatus.status === "success") break;  if (finalStatus.status === "failed") {    throw new Error(finalStatus.failureMessage || "Encoding failed");  }
  await new Promise((resolve) => setTimeout(resolve, 5000));}
console.log(finalStatus.downloadUrl);console.log(finalStatus.requestedExecution);console.log(finalStatus.effectiveExecution);console.log(finalStatus.sourceProbe?.color);console.log(finalStatus.outputProbe);

const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  externalId: "customer-video-123",  metadata: {    customerId: "cus_123",    workflow: "daily-compression",  },  codec: "h264",  resolution: "1080p",  quality: "better",  audioPolicy: "transcode-aac",  frameRatePolicy: "cap",  scalePolicy: "no-upscale",}, {  idempotencyKey: "encode-customer-video-123",});
let finalStatus;while (true) {  finalStatus = await client.onDemandStatus(job.jobId);
  if (finalStatus.status === "success") break;  if (finalStatus.status === "failed") {    throw new Error(finalStatus.failureMessage || "Encoding failed");  }
  await new Promise((resolve) => setTimeout(resolve, 5000));}
console.log(finalStatus.downloadUrl);console.log(finalStatus.requestedExecution);console.log(finalStatus.effectiveExecution);console.log(finalStatus.sourceProbe?.color);console.log(finalStatus.outputProbe);

Terminal users can inspect the same report with:

URL Source To S3 Output

const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  codec: "h264",  resolution: "1080p",  outputS3: {    bucket: "customer-output-bucket",    key: "encoded/input-1080p.mp4",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },});
console.log(job.jobId);

const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  codec: "h264",  resolution: "1080p",  outputS3: {    bucket: "customer-output-bucket",    key: "encoded/input-1080p.mp4",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },});
console.log(job.jobId);

For S3-compatible services, pass endpoint and usually forcePathStyle: true.

URL Source To Google Drive Output

For headless API integrations, save a customer-owned Google service account once. Use a Google Shared Drive for output and add the returned service-account email as a member with permission to create files.

const credential = await client.createGoogleDriveCredential({  name: "Production Drive",  serviceAccount: JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_JSON!),});
const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  codec: "h264",  resolution: "1080p",  outputGoogleDrive: {    folderId: "GOOGLE_DRIVE_FOLDER_ID",    fileName: "input-1080p.mp4",    credentialId: credential.id,  },});
console.log(job.jobId);

const credential = await client.createGoogleDriveCredential({  name: "Production Drive",  serviceAccount: JSON.parse(process.env.GOOGLE_SERVICE_ACCOUNT_JSON!),});
const job = await client.onDemandEncode({  sourceUrl: "https://example.com/input.mp4",  codec: "h264",  resolution: "1080p",  outputGoogleDrive: {    folderId: "GOOGLE_DRIVE_FOLDER_ID",    fileName: "input-1080p.mp4",    credentialId: credential.id,  },});
console.log(job.jobId);

Dashboard Google Picker authorization is separate from SDK automation.

Folder Ingest

Queue one job per video in an S3 prefix:

const batch = await client.onDemandIngestFolder({  externalIdPrefix: "batch-2026-06-09",  metadata: {    customerId: "cus_123",    workflow: "folder-compression",  },  sourceS3: {    bucket: "customer-source-bucket",    prefix: "incoming/",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },  outputDestination: "s3",  outputS3: {    bucket: "customer-output-bucket",    prefix: "encoded/",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },  codec: "h264",  maxFiles: 25,  resolution: "1080p",}, {  idempotencyKey: "folder-batch-2026-06-09",});
for (const job of batch.jobs || []) {  console.log(job.jobId, job.externalId, job.fileName);}

const batch = await client.onDemandIngestFolder({  externalIdPrefix: "batch-2026-06-09",  metadata: {    customerId: "cus_123",    workflow: "folder-compression",  },  sourceS3: {    bucket: "customer-source-bucket",    prefix: "incoming/",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },  outputDestination: "s3",  outputS3: {    bucket: "customer-output-bucket",    prefix: "encoded/",    region: "us-east-1",    accessKeyId: process.env.CUSTOMER_S3_ACCESS_KEY_ID,    secretAccessKey: process.env.CUSTOMER_S3_SECRET_ACCESS_KEY,  },  codec: "h264",  maxFiles: 25,  resolution: "1080p",}, {  idempotencyKey: "folder-batch-2026-06-09",});
for (const job of batch.jobs || []) {  console.log(job.jobId, job.externalId, job.fileName);}

Use maxFiles to cap how many discovered videos are queued from a folder.

Queue one job per video in a Google Drive folder:

const batch = await client.onDemandIngestFolder({  sourceGoogleDrive: {    folderId: "SOURCE_FOLDER_ID",    credentialId: credential.id,  },  outputDestination: "google-drive",  outputGoogleDrive: {    folderId: "OUTPUT_FOLDER_ID",    credentialId: credential.id,  },  codec: "h264",  maxFiles: 25,  resolution: "1080p",});
for (const job of batch.jobs || []) {  console.log(job.jobId, job.fileName);}

const batch = await client.onDemandIngestFolder({  sourceGoogleDrive: {    folderId: "SOURCE_FOLDER_ID",    credentialId: credential.id,  },  outputDestination: "google-drive",  outputGoogleDrive: {    folderId: "OUTPUT_FOLDER_ID",    credentialId: credential.id,  },  codec: "h264",  maxFiles: 25,  resolution: "1080p",});
for (const job of batch.jobs || []) {  console.log(job.jobId, job.fileName);}

Convertrilo mints short-lived Google tokens from the encrypted service-account credential when each worker starts.

Poll each returned jobId with client.onDemandStatus(jobId).

Webhook Delivery History

Managed webhooks are HMAC signed. You can test a webhook and inspect recent delivery attempts:

await client.testWebhook(webhookId);
const history = await client.getWebhookDeliveries(webhookId);for (const delivery of history.deliveries || []) {  console.log(delivery.status, delivery.statusCode, delivery.event);}

await client.testWebhook(webhookId);
const history = await client.getWebhookDeliveries(webhookId);for (const delivery of history.deliveries || []) {  console.log(delivery.status, delivery.statusCode, delivery.event);}

Regenerate Types

The SDK types are generated from openapi.yaml.

The generate script uses --default-non-nullable false so OpenAPI defaults remain optional in TypeScript request bodies.

Source: README.md at commit d4ff8b2

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts