OS OpenShorts GitHub

Automation

OpenShorts MCP server, wired to your own pipeline

The repo ships a remote MCP server beside the dashboard: same API, same keys, eight tools that call it in-process. This page is the endpoint, the client command, and what each tool actually takes.

The MCP server is not a separate service. It lives inside the backend at /mcp, and every tool call is turned into an in-process HTTP call against the same routes the dashboard uses. That one design choice explains most of its behaviour: the agent inherits your auth, your quota and your keys, and nothing has to be kept in sync.

The endpoint is just /mcp on the backend

Self-hosted, that is http://localhost:8000/mcp — port 8000, the API port, not the dashboard on 5175. The cloud runs the identical endpoint at https://mcp.openshorts.app/mcp, with api.openshorts.app/mcp serving the same thing.

Property Value
Transport Streamable HTTP, plain JSON responses
Sessions None — stateless, no session ids, no SSE stream
Protocol versions accepted 2025-06-18, 2025-03-26, 2024-11-05
Methods used initialize, tools/list, tools/call, notifications
Self-host auth None required (BYOK): X-Gemini-Key header or the env value
Cloud auth Authorization: Bearer osk_... — the key is the account

Because the transport is stateless, you can restart the backend between calls without breaking a client, and you do not need a long-lived connection open for a job to finish.

Connect a client in one command

With Claude Code or any client that speaks HTTP MCP, the self-hosted server needs no header at all:

claude mcp add --transport http openshorts http://localhost:8000/mcp

On the cloud, add the bearer header:

claude mcp add --transport http openshorts https://mcp.openshorts.app/mcp \
  --header "Authorization: Bearer osk_..."

Any client that takes a JSON config works the same way: point it at the URL and, for cloud, the bearer header. If you are running the stack in Docker on the same machine, localhost:8000 from the host reaches the backend; from another container, use the service name backend and the internal port 8000.

The eight tools

Tool What it does
process_video Starts a clipping job from a URL or an uploaded file
create_upload Returns a presigned URL for a local file
get_job_status Progress, the last log lines, and the clips produced so far
list_clips The clips a job produced
get_quota Remaining plan minutes (cloud) or a no-quota note (self-host)
add_subtitles Re-styles or re-times captions on an existing clip
recut_clip Cuts a new clip out of an existing one by timestamp ranges
publish_clip Posts a finished clip to a social platform

process_video carries the whole configuration surface. The parameters that change the output:

Parameter Values Default
source_url or upload_id A video URL, or the id from create_upload required
confirm_rights true — you assert you have the rights to the source required
target_clips 1–15 5
clip_min_seconds / clip_max_seconds 5–175 / 10–180 15 / 60
layouts auto, split, screencast, speaker_cut, punch_in auto
output_format auto, vertical, horizontal, square auto
auto_hook / hook_style boolean; pill, classic, dark, yellow, red, outline, outline_yellow true / pill
captions boolean true
webhook_url, webhook_secret Optional completion callback —
force_low_quality true skips the low-resolution confirmation gate false

One job, end to end

A minimum call looks like this. confirm_rights is not optional — without it the call is refused, because the pipeline sends frames to third-party models.

{
  "source_url": "https://www.youtube.com/watch?v=...",
  "confirm_rights": true,
  "target_clips": 3,
  "output_format": "vertical"
}

Then poll get_job_status every 30–60 seconds. It returns a status of queued, processing, completed or failed, the last ten log lines, and each clip with its index, title, duration, video_url and the source segments it came from. A failed job comes back with the log line that explains it rather than a bare error.

Clips arrive with ready-made youtube_title, tiktok_description and instagram_description fields, so an agent can publish without writing copy again. publish_clip accepts tiktok (as a draft), instagram, youtube, facebook, linkedin, threads and bluesky, plus an optional ISO-8601 scheduled_date.

Uploads, webhooks and where the limits are

create_upload returns a URL you PUT the raw bytes to — curl -T file.mp4 "$URL" is enough — and the URL expires in six hours. If a machine dies mid-upload, ask for a new one; do not reuse the old URL.

Set webhook_url and webhook_secret on process_video and the server POSTs to you when the job finishes, signed with HMAC-SHA256 in the X-OpenShorts-Signature header. Verify that header before acting on the payload; anyone who knows your URL can otherwise post a fake "completed".

Four errors are worth wiring into your client:

  • quota_exceeded (cloud) — the response carries an upgrade_url.
  • no_plan (cloud) — the key is valid but has no plan attached.
  • needs_confirmation — the source is under the quality gate; retry with force_low_quality if you mean it.
  • 404 Job not found — cloud jobs are removed from local disk about an hour after they finish, and the API restores the project from storage. A job id from yesterday still works; a job from last month may not.

Self-hosted has no minute quota at all — get_quota says so — which is why the cost conversation here is about your own model bill, not a plan.

Self-host auth versus cloud auth

Self-hosted, the MCP server is BYOK and unauthenticated: whoever can reach port 8000 can start a job with your keys. That is fine on a laptop and not fine on a public VPS — put it behind a firewall or a reverse proxy with auth before you expose it. Cloud, the osk_ key scopes every call to one account, and gating happens exactly as it does for dashboard requests.

The REST routes behind the tools

If you would rather call the API directly than speak MCP, the same operations are plain REST routes on the same port:

Route Equivalent
POST /api/process process_video
POST /api/uploads create_upload
GET /api/status/{job_id} get_job_status
POST /api/subtitle add_subtitles
POST /api/clip/rerender recut_clip
POST /api/social/post publish_clip
GET /api/me get_quota

For where the keys themselves go, see the API keys page; for a job that dies halfway, the troubleshooting page opens with the log commands.