@kolbo/mcp

Use Kolbo AI as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).

Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.

✨ Interactive widgets (v1.30+): in claude.ai, Claude Desktop, and Codex Desktop, generations render as live Kolbo cards — real-time progress with model + settings chips, an inline result gallery / video or audio player, and one-click Animate · Edit · Recreate · Download actions. Multi-audio generations render every track with its own player and Download button. Library and model searches render as browsable grids with audio preview. Text-only clients (Claude Code, Codex CLI, Cursor) keep the classic text responses.

Set up — paste one prompt, or one config block (keyless, no API key)

Easiest: paste this prompt to your AI

Copy this and paste it to Claude, ChatGPT, Cursor, or any AI assistant — it installs Kolbo itself (picks local config or remote connector based on what it can do):

Connect the Kolbo AI MCP server (generate images, video, music and more).

- If you can run terminal commands (Claude Code, Cursor, Claude Desktop, or any local setup): run "npx -y @kolbo/mcp install" — it auto-configures Kolbo in the right place. If you can't run it, give me the command to run. Then I'll restart the app.
- If you're a browser chat (claude.ai, ChatGPT): add a custom connector with URL https://api.kolbo.ai/mcp under Settings → Connectors, then Connect → log in → Allow.

No API key needed — on first use a Kolbo login opens in my browser and I click Allow. When set up, confirm Kolbo is connected and offer to generate a test image of a sunset.

Or set it up yourself — one command

Run this once — it sets up the full Kolbo experience (the MCP tools and the routing skill) for every installed agent (Claude Desktop, Claude Code, Cursor), keyless:

npx -y @kolbo/mcp install

Or add the config by hand — this block is identical for every MCP client and carries no API key (on first use it logs you in via the browser):

{
  "mcpServers": {
    "kolbo": {
      "command": "npx",
      "args": ["-y", "@kolbo/mcp@latest"]
    }
  }
}

| Client | Where the config goes | |--------|----------------------| | Claude Code | ~/.claude.json (or claude mcp add kolbo -- npx -y @kolbo/mcp@latest) | | Claude Desktop | claude_desktop_config.json | | Cursor | .cursor/mcp.json | | Kolbo Code | configured automatically on kolbo auth login |

Restart your app, then ask it to generate something. The first time, a Kolbo login opens in your browser — click Allow (no API key to create). Prefer an API key? Create one at app.kolbo.ai/developer and add "env": { "KOLBO_API_KEY": "kolbo_live_..." } to the block above.

Browser-only (claude.ai / ChatGPT / Codex): connector + skill

1. Add the custom connector https://api.kolbo.ai/mcp under Settings → Connectors, then Connect → log in → Allow.
2. Download the Skill and upload it (Claude.ai: Settings → Features → Skills; ChatGPT/Codex: Settings → Skills). Codex CLI: unzip into ~/.codex/skills/.

The Skill is the canonical routing layer. Without it the tools still work, but the model will not load Seedance / Visual DNA / filmmaking rules.

Optional upgrade: add the Kolbo skill for slash-commands + smart routing

The config above is all you need. If you want one-word slash-commands (/kolbo:marketing-studio, /kolbo:product-photoshoot, …) and automatic routing to the best tool with the right defaults, install the Kolbo skill on top — it's an enhancement layer, not a requirement:

# Claude Code plugin (canonical skill + MCP configuration)
claude plugin marketplace add Zoharvan12/kolbo-claude-plugin
claude plugin install kolbo@kolbo

# Skill only — installs the bundled official skill without changing MCP settings
npx -y @kolbo/mcp@latest skill

The skill-only command installs the canonical single kolbo skill and does not change MCP configuration. The Claude Code plugin and npx -y @kolbo/mcp install routes configure MCP as well. Official installer-created skill folders are marked as Kolbo-managed and refresh automatically when the MCP server starts on a newer package; unmarked or hand-authored folders are never overwritten. The canonical skill ships inside Kolbo Code, so however you connect, the behavior matches. See the full setup guide at docs.kolbo.ai/developer-api/claude-code-skill.

Use it

Just ask your agent naturally:

Generation

• "Generate an image of a sunset over mountains"
• "Create a 5-second video of waves crashing"
• "Build a 4-scene storyboard for a coffee shop ad"
• "Remove the background from this image"
• "Make a lo-fi hip hop beat"
• "Read this out loud with a British female voice"

Marketing & UGC

• "Make me a UGC ad for my sneaker brand — 9:16, talking-head style"
• "TV spot for my new beverage, 15 seconds, cinematic"
• "Unboxing video for this product photo"

Brand & product imagery

• "Pinterest pin for my candle brand, cottagecore mood"
• "Hero banner for my landing page, wide format"
• "Lifestyle shot of my product in a kitchen"
• "4 ad creative variants for Meta and TikTok"

Marketplace listings

• "Generate Amazon main image + 5 secondary images for my product"
• "Full A+ content set for my Shopify listing"

Analysis & utility

• "Ask Claude about the latest AI news with web search on"
• "Analyze this video and tell me what prompts are shown on screen"
• "What's in this image?"
• "Create a Visual DNA profile called 'Alex' from these images"
• "Use the same brand as last time" (loads a persisted brand kit from the workspace)

Without the optional skill, the config block alone already exposes every tool — you just describe what you want. With the skill installed, each of these is also routed to the right MCP tool with the right defaults — UGC mode picks 9:16 + sound-off + no-captions, marketplace mode enforces compliance (pure white bg, no text, no props), product photoshoot mode uses the right aspect for the platform (2:3 Pinterest, 16:9 hero banner, 1:1 IG feed), etc. The routing logic is shared with Kolbo Code, so the behavior is identical however you connect.

Available Tools

Generation | Tool | Description | |------|-------------| | generate_image | Text → image. Supports preset_id from list_presets type="image". | | generate_image_edit | Existing image(s) + prompt → edited image. Supports preset_id from list_presets type="image_edit". | | generate_video | Text → video | | generate_video_from_image | Still image + motion prompt → video | | generate_video_from_video | Input video → restyled video, or burn in subtitles (video-to-video). prompt optional — prompt-less models (VEED Subtitles, Act Two, Wan Animate) use preset / source_language / translation_language, plus srt_content / srt_file_url / vocabulary / customization for VEED | | generate_elements | Reference images/videos/audio + prompt → animated video | | generate_first_last_frame | First frame + last frame → interpolated video | | generate_lipsync | Source image/video + audio → lipsynced video (Sync-3 adds active-speaker selection, emotion, model mode, temperature) | | generate_creative_director | One brief → N coordinated scenes (image or video) | | generate_music | Text (+ optional lyrics) → song. Style, title, negative tags, length, and Suno fine-controls (style weight, weirdness, audio weight, persona / singing voice) | | generate_speech | Text + voice → spoken audio. Full expressive/style control: Google/Gemini named voice-direction presets (style_instructions_preset_id: warm/dramatic/whisper/…) or free-form style_instructions, preset styles + emotions (DeepDub / MiniMax / Cartesia), speed, accent/language, and per-provider voice settings (ElevenLabs similarity/style, DeepDub accent/variance/tempo, MiniMax pitch/volume/intensity/timbre). Status returns the same fields for reuse. | | generate_sound | Text → sound effect. Duration, prompt influence, and per-provider controls (Stable Audio guidance, Kie loop/tempo/key, Seed-Audio voice/speed/volume/pitch + reference audio/image) | | generate_3d | Text or reference images → 3D model (GLB/FBX/OBJ/USDZ) | | transcribe_audio | Audio/video URL or file → text + SRT subtitles. Language, speaker diarization, audio-event tagging, and SRT formatting (words/line, lines/subtitle, caption stretch) | | separate_audio_stems | Audio/video URL (or a Kolbo generation_id) → Dialogue / Music / Effects / without-dialogue (M&E) layers. Kolbo's own masking pipeline with a speech classifier on top, so a centred engine or ambience is not handed back mislabelled as dialogue. 5 credits, runs inline | | clean_dialogue_leftovers | Strip voices still faintly audible in an M&E layer. 17 credits — escalation only, it trades bed fidelity to remove the leak | | separate_ambience | Pull room tone / atmosphere out of the Effects (or Music) bed as its own layer. 17 credits |

Every image/video/creative-director tool accepts visual_dna_ids and moodboard_id for character/style consistency across outputs — you can compose create_visual_dna → generate_image (with the DNA applied server-side) in a single agent turn. generate_creative_director also accepts moodboard_ids plural for blending.

Every generation tool also accepts an optional resolution arg. Images use "1K" (~1024px) / "2K" (Full HD) / "3K" (QHD) / "4K" (UHD); videos use vertical-pixel tiers like "720p" / "1080p" / "1440p" / "2160p". Values are model-dependent — call list_models and read the chosen model's supported_resolutions and resolutionMultipliers. Omit to use the model default.

Every generation tool also accepts an optional project_id arg that routes the generation into a specific project (owned or shared with edit+). Call list_projects to discover IDs. When omitted, generations land in the user's auto-created "API Generations" project. project_id is per-call, NOT sticky — pass it on every call once the user names a working project. Misplaced work is recoverable via move_media / move_session.

Chat & Vision | Tool | Description | |------|-------------| | chat_send_message | Multi-turn chat with any Kolbo model. Pass media_urls to analyze images, videos, or audio — auto-routes to Gemini for vision. Supports web search and deep think. | | chat_list_conversations | List past chat threads | | chat_get_messages | Fetch messages in a conversation |

Visual DNA (reusable character/style/product profiles) | Tool | Description | |------|-------------| | create_visual_dna | Create a profile from URLs or local files | | update_visual_dna | Edit name, description, stills, sheet, or type in place (never delete+recreate) | | list_visual_dnas | List your profiles | | get_visual_dna | Fetch one profile | | delete_visual_dna | Delete a profile |

Moodboards | Tool | Description | |------|-------------| | list_moodboards | Browse presets + your moodboards | | get_moodboard | Fetch one moodboard with all image URLs | | create_moodboard / update_moodboard / delete_moodboard | Create / edit in place / delete |

Color DNA — sticky, account-wide: the ACTIVE palette strict-grades every generation until deactivated. Opt a single generation out with skip_color_palette. | Tool | Description | |------|-------------| | list_color_palettes | List your palettes (+ org) | | analyze_color_palette | Extract colors from 1-5 image URLs (free, does not save) | | create_color_palette | Save a palette (colors from analyze or manual); auto-activates by default | | update_color_palette | Rename / replace colors | | delete_color_palette | Delete a palette | | activate_color_palette | Make a palette the sticky active one | | deactivate_color_palette | Clear the active palette |

Media Library | Tool | Description | |------|-------------| | media_upload_widget | Open an in-chat upload card so claude.ai users can upload LOCAL files (image / video / audio / document) — chat attachments are unreachable from remote MCP, so this is the way to bring them in. Returns stable CDN URLs | | create_upload_ticket | Get a short-lived upload ticket and POST local files yourself — no upload card, no user interaction. For agents with shell access (Claude Code, Codex, Cursor, CI) talking to Kolbo over a remote connector | | upload_media | Upload a local file (path or URL), or inline source_base64 + filename, → stable Kolbo CDN URL for reuse | | list_media | Browse media library — filter by project_id, folder_id, type, category (ai / uploaded / edited / favorites / training-lab), source_type, sort, search, pagination | | list_media_folders | List the user's media folders (owned + shared) — discover folder_id values to pass to list_media | | create_media_folder | Create a new folder (name, optional description / color / icon) | | update_media_folder | Rename / recolor / re-icon a folder (owner only) | | delete_media_folder | Soft-delete a folder (owner only; items remain in library) | | add_media_to_folder | Add up to 500 media items to a folder (idempotent) | | remove_media_from_folder | Remove media items from a folder | | share_media_folder | Share a folder by user email (owner only) | | unshare_media_folder | Revoke a user's access to a folder (owner only) | | favorite_media | Mark a media item as favorited (idempotent) — pass media_id from list_media | | unfavorite_media | Remove a media item from favorites (idempotent) — pass media_id from list_media | | get_media | Fetch one media item's full details by id | | delete_media | Soft-delete a media item (30-day trash) | | restore_media | Restore a trashed item | | permanently_delete_media | Hard-delete (NOT reversible — confirm with user first) | | move_media | Re-assign a media item to a different project | | bulk_delete_media | Soft-delete up to 1000 items in one call | | bulk_restore_media | Restore up to 1000 trashed items | | bulk_permanently_delete_media | Hard-delete up to 1000 (NOT reversible) | | bulk_move_media | Move up to 1000 items to a project (atomic — all-or-nothing) | | move_folder_contents | Move every item in a folder to a project | | get_media_stats | Counts + storage bytes per type (optionally per project) |

Artifacts | Tool | Description | |------|-------------| | publish_html_artifact | Publish an HTML page, SVG, or Mermaid diagram and get a public shareable URL on sites.kolbo.ai. Pass share_token from a prior publish to update the same URL in place (old content kept in version history). |

SYNCI Music Library (licensed production music) | Tool | Description | |------|-------------| | search_music_library | Search the licensed catalog; results contain watermarked previews only. | | analyze_script_for_music | Turn a script or scene description into a music search. | | browse_music_library | Browse the catalog without a query. | | get_music_library_facets | List genres, moods, instruments, BPM, and duration filters. | | get_music_track_audio | Get watermarked preview URLs for a track. | | acquire_clean_music_track | Spend one SYNCI vendor credit and return clean MP3/WAV signed URLs. Idempotent with request_id. | | import_music_track_to_library | Spend one vendor credit and copy a clean MP3/WAV into Kolbo's media library. | | get_music_track_related | Get stems/alternate-version metadata (purchasing remains unsupported). | | get_music_track_lyrics | Get lyrics metadata. |

Stock Library (multi-source stock media: Pexels, Pixabay, Sketchfab 3D, Music) | Tool | Description | |------|-------------| | search_stock_media | Search photos/videos/illustrations/vectors/3D/music across providers. source="all" returns one interleaved feed. Find ready-made assets / b-roll (distinct from generate_image/generate_video). | | get_stock_sources | List enabled sources + which media types/filters each supports. | | get_stock_categories | List dynamic category/topic chips (pass providerParam as the category filter). | | get_stock_asset | Get one asset with all download variants, author, license, and attribution. | | analyze_script_for_stock | AI: turn a script into b-roll search terms (queries[], mediaType, keywords). | | import_stock_asset | Copy a stock asset into the media library (CDN copy, stable URL). Free. |

Blender Bridge | Tool | Description | |------|-------------| | blender_list_sessions | List the caller's connected Blender processes before choosing a target session | | blender_get_scene | Queue a bounded scene summary or full scene inspection | | blender_search_docs | Inspect local Blender RNA and return relevant official API/manual URLs without fetching them | | blender_capture_viewport | Capture the active viewport to managed cache and optionally Kolbo media | | blender_apply_operations | Apply approved structured object, material, world, camera, light, animation, duplication, or deletion operations | | blender_import_media | Import a Kolbo media item or exact-allowlisted Kolbo-owned HTTPS media/CDN asset using smart GLB/image/video placement | | blender_render | Render a still or an animation capped by Blender at 250 scene frames and 100,000,000 pixel-frames, to managed output and optionally Kolbo media | | blender_undo | Undo the most recent Blender change in the selected process | | blender_file_operation | Perform sensitive new/open/save/save-as operations with in-Blender approval | | blender_execute_python | Execute explicitly reviewed Python plus a required plain-language purpose with full host authority; approval required unless trusted mode is visibly active | | blender_get_command_status | Read bounded command status/result/error plus absolute expires_at; records and idempotency claims expire after 24 hours, and awaiting_approval means stop and wait for the user |

Discovery & Account | Tool | Description | |------|-------------| | list_models | Current model catalog with costs and capabilities | | list_voices | TTS voices (presets + cloned) | | list_presets | Generation presets across image/image-edit/video/music/text-to-video catalogs. Pass the selected exact id as preset_id; never claim a preset was applied without it. | | list_cinematic_presets | "Cinema mode" presets grouped by dimension (camera, lens, focal_length, aperture, angle, shot_type, color_palette, lighting) — pass ids via the cinematic arg on generate_image / generate_image_edit. Only when the user wants a specific cinematic look | | list_projects | List owned + shared projects (id, name, description, role, is_default) — call first to resolve a project name into the project_id you pass to generation tools | | get_project | Full project record including the unclipped description — read this before update_project | | move_session | Move ONE session (generation, chat, transcription…) and ALL its generations + media to another project | | bulk_move_sessions | Move up to 100 sessions into one project in a single call — mixed types allowed, per-session failures reported | | list_session_generations | A session's generations as complete groups (prompt + all its outputs) — the ids the two organize tools below take | | move_generations_to_session | Move selected generations (and only THEIR output media) into another existing session | | split_session | Carve selected generations out into a brand-new named session, atomically | | undo_session_organization | Reverse a move/split within 15 minutes, using the operation_id it returned | | create_doc / list_docs / get_doc / update_doc / share_doc / delete_doc | AI Docs (Magic Pad): author project-scoped HTML documents, edit them, get public share links | | generate_character_sheet | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna or update_visual_dna | | list_visual_dna_folders / create_visual_dna_folder / update_visual_dna_folder / delete_visual_dna_folder / move_visual_dna_to_folder | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) | | create_project / update_project / archive_project / unarchive_project | Project lifecycle (create/rename/describe/archive; deletion stays in-app) | | list_agents / create_agent / update_agent / delete_agent | Custom chat agents (reusable named personas; description is the system instruction) | | get_creative_director_status | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a _timed_out Director run) | | list_sessions | Enumerate sessions across all types, filterable by project, type, and types[] | | rename_session / delete_session / restore_session | Rename a session; soft-delete leftovers after a move; restore from trash | | add_project_context / list_project_context / delete_project_context / get_project_profile / regenerate_project_profile | Project knowledge base (RAG): feed scripts/URLs/notes, read the synthesized living brief | | list_project_assets / link_project_asset / unlink_project_asset / update_project_asset | Project cast: tag Visual DNAs / moodboards onto a project, write each DNA's description and purpose note | | create_moodboard / update_moodboard / delete_moodboard | Build/edit moodboards from image URLs (AI style analysis → master prompt) | | clone_voice / import_elevenlabs_voice / delete_voice | Custom voices: clone from an audio sample, import by ElevenLabs ID, delete | | trim_video | Frame-accurate server-side trim of a Kolbo-hosted video (async job, tool waits) | | check_credits | Check credit balance | | get_generation_status | Check one or many generations (generation_ids); wait=true blocks server-side until done — replaces client polling loops |

Environment Variables

Both are optional — the local install logs in via the browser on first use.

| Variable | Required | Description | |----------|----------|-------------| | KOLBO_API_KEY | No | Set a kolbo_live_ key to skip the browser login (create one at app.kolbo.ai/developer). | | KOLBO_API_URL | No | Custom API URL (default: https://api.kolbo.ai/api) |

Links

• API Documentation
• Kolbo AI Platform
• Get API Key

Chat thinking level

chat_send_message accepts optional thinking_level, using an ID from list_models with type: "text". The server validates it against the resolved model; omitted or invalid values use thinkingDefault. Existing safeguards and legacy deep_think take precedence. Discover allowed levels through thinkingLevels; no package update is required when the server changes a model capability.