Convertrilo MCP server

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

pnpm add @convertrilo/sdk

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:

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:

convertrilo completion zsh

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,
});

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",
});

Shortened. The full README is on GitHub.