English Français العربية

io.github.luke-fairbanks/broll

السجل الرسمي أدوات المطورين

Content studio MCP for coding agents: BYO keys, deterministic video rendering, draft-first posting

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package broll-mcp
Claude Code 
claude mcp add broll -e 'OPENAI_API_KEY=<your openai_api_key>' -e 'GEMINI_API_KEY=<your gemini_api_key>' -e 'BLUESKY_IDENTIFIER=<BLUESKY_IDENTIFIER>' -e 'BLUESKY_APP_PASSWORD=<your bluesky_app_password>' -e 'MASTODON_ACCESS_TOKEN=<your mastodon_access_token>' -e 'X_API_KEY=<your x_api_key>' -e 'X_API_SECRET=<your x_api_secret>' -e 'X_ACCESS_TOKEN=<your x_access_token>' -e 'X_ACCESS_TOKEN_SECRET=<your x_access_token_secret>' -- npx -y broll-mcp@0.1.1
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "broll": {
            "command": "npx",
            "args": [
                "-y",
                "broll-mcp@0.1.1"
            ],
            "env": {
                "OPENAI_API_KEY": "<your openai_api_key>",
                "GEMINI_API_KEY": "<your gemini_api_key>",
                "BLUESKY_IDENTIFIER": "<BLUESKY_IDENTIFIER>",
                "BLUESKY_APP_PASSWORD": "<your bluesky_app_password>",
                "MASTODON_ACCESS_TOKEN": "<your mastodon_access_token>",
                "X_API_KEY": "<your x_api_key>",
                "X_API_SECRET": "<your x_api_secret>",
                "X_ACCESS_TOKEN": "<your x_access_token>",
                "X_ACCESS_TOKEN_SECRET": "<your x_access_token_secret>"
            }
        }
    }
}

متغيرات البيئة

  • OPENAI_API_KEY سري Optional: gpt-image-1 image generation
  • GEMINI_API_KEY سري Optional: Imagen images + Veo video
  • BLUESKY_IDENTIFIER Optional: Bluesky handle for live posting
  • BLUESKY_APP_PASSWORD سري Optional: Bluesky app password
  • MASTODON_ACCESS_TOKEN سري Optional: Mastodon app token for live posting
  • X_API_KEY سري Optional: X consumer key (posting requires funded API credits)
  • X_API_SECRET سري Optional: X consumer secret
  • X_ACCESS_TOKEN سري Optional: X access token (Read and write)
  • X_ACCESS_TOKEN_SECRET سري Optional: X access token secret

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. broll
  2. Why
  3. Install
  4. Tools
  5. Try it
  6. broll cloud (waitlist)
  7. Safety model
  8. Status & roadmap
  9. Development

broll

The content studio MCP for coding agents. broll gives Claude Code, Codex, and any MCP client real hands for content work: generate media with your own API keys, render videos and carousels deterministically with code, and publish through a draft-first outbox.

The model plans. Code renders. Nothing posts without confirmation.

Why

Every developer running a coding agent hits the same wall: the agent can write the marketing plan, but it can't make the carousel, cut the video, or post it. Existing tools are credit-metered schedulers built for social media managers. broll is built for developers:

  • BYO keys, no markup. Image/video generation uses your OPENAI_API_KEY / GEMINI_API_KEY directly. broll never proxies your inference or resells credits. A built-in mock provider keeps every workflow runnable before you add any keys.
  • Deterministic rendering. Videos and slides are compiled from declarative plans into exact ffmpeg/sharp invocations. Same plan + same inputs = same output. When AI output drifts, the fix is code — so layout, fonts, captions, and branding live in code.
  • Draft-first publishing. Posts are reviewable JSON files in an outbox. publish_post requires confirm: true, validates per-platform rules (char limits, media counts, file sizes) before anything leaves the machine, and reports per-platform results. The export platform always works: it writes a ready-to-post bundle.

Install

Requires Node 20+ and ffmpeg (brew install ffmpeg).

cd broll
npm install && npm run build

Register with Claude Code (or use the checked-in .mcp.json when working inside this repo):

claude mcp add broll -- node /path/to/broll/dist/index.js

Optional environment:

VariablePurpose
OPENAI_API_KEYgpt-image-1 image generation
GEMINI_API_KEYImagen images + Veo video generation
BLUESKY_IDENTIFIER / BLUESKY_APP_PASSWORDlive Bluesky posting (use an app password)
MASTODON_ACCESS_TOKEN (+ optional MASTODON_INSTANCE)live Mastodon posting — no app review, any instance
X_API_KEY / X_API_SECRET / X_ACCESS_TOKEN / X_ACCESS_TOKEN_SECRETlive X posting (free API tier works)
BROLL_HOMEworkspace location (default ~/.broll)
BROLL_FFMPEG / BROLL_FFPROBEexplicit binary paths

Brand kit: drop a broll.config.json next to where the server runs (see this repo's for an example) — name, handle, colors, font, logo. Every render picks it up automatically.

Tools

ToolWhat it does
broll_statusWorkspace, ffmpeg, provider + platform readiness. Call first.
generate_image / generate_videoBYO-key generation → workspace assets (mock fallback when keyless)
import_asset / list_assets / probe_assetBring in and inspect media
render_videoDeclarative RenderPlan → mp4: clips (video/image/color), trims, cover/contain fits, burned-in titles + timed captions, music bed, 9:16 / 1:1 / 4:5 / 16:9
render_carouselBranded slide sets (the Instagram/LinkedIn format): kicker, headline, body, accent bar, page numbers, watermark — layout is 100% code
extract_framePull a PNG frame so the agent can visually QA its own render
create_post_draftText + media + platforms → validated, reviewable draft in the outbox
list_drafts / publish_postInspect the outbox; publish with explicit confirm: true

Try it

npm run smoke

drives the real server through a real MCP client: generates a background, renders a 3-slide carousel and a 9:16 teaser video with captions, extracts a QA frame, then drafts and "publishes" an export bundle — all into ./.broll/.

broll cloud (waitlist)

The local server you're looking at stays MIT and free. broll cloud adds the parts a local server can't do well: the app-review-walled platforms (Instagram, LinkedIn, TikTok) through broll's own approved credentials, schedules that run while your laptop is closed, and a swipe-to-approve inbox on your phone. ~$29/mo when it ships.

Join the waitlist → 👍 issue #1 — subscribers get the launch note; comments set the platform build order.

Safety model

  1. Nothing is published without a draft file on disk first.
  2. publish_post hard-requires confirm: true — agents are instructed to obtain the user's explicit go-ahead.
  3. Constraint violations block publishing; they never auto-truncate your text.
  4. Keys are read from your environment and sent only to their own vendor's API.

Status & roadmap

Early but real: 96 tests including real-ffmpeg integration renders and a full MCP round trip.

  • [ ] Bluesky video upload
  • [ ] X chunked video upload
  • [ ] LinkedIn adapter (needs app review)
  • [x] Mastodon adapter
  • [ ] YouTube Shorts via user OAuth
  • [ ] Ken Burns / crossfade transitions
  • [ ] Word-level caption timing from transcripts
  • [ ] npx broll-mcp distribution

Development

npm test          # unit + integration (real ffmpeg)
npm run typecheck
npm run smoke     # end-to-end artifact check

MIT.

الأسئلة الشائعة

ما هو io.github.luke-fairbanks/broll؟

Content studio MCP for coding agents: BYO keys, deterministic video rendering, draft-first posting

كيف أثبّت io.github.luke-fairbanks/broll؟

يعمل على جهازك. في Claude Code: claude mcp add broll -e 'OPENAI_API_KEY=<your openai_api_key>' -e 'GEMINI_API_KEY=<your gemini_api_key>' -e 'BLUESKY_IDENTIFIER=<BLUESKY_IDENTIFIER>' -e 'BLUESKY_APP_PASSWORD=<your bluesky_app_password>' -e 'MASTODON_ACCESS_TOKEN=<your mastodon_access_token>' -e 'X_API_KEY=<your x_api_key>' -e 'X_API_SECRET=<your x_api_secret>' -e 'X_ACCESS_TOKEN=<your x_access_token>' -e 'X_ACCESS_TOKEN_SECRET=<your x_access_token_secret>' -- npx -y broll-mcp@0.1.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.luke-fairbanks/broll إلى مفتاح API؟

نعم. يتطلب OPENAI_API_KEY, GEMINI_API_KEY, BLUESKY_APP_PASSWORD, MASTODON_ACCESS_TOKEN, X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET، وتضبطها في إعداداته.

هل io.github.luke-fairbanks/broll مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.luke-fairbanks/broll؟

ينشره luke-fairbanks. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.