naman-sharma12345/kimo

kimo

A video editor an AI can drive. MCP-first. Every feature is a tool call. Written in Rust, CPU renderer, runs on a 2 GB box. getkimo.tech

---

What it is

kimo is a video editor with no GUI. You talk to it over the Model Context Protocol. Cut, keyframe, grade, track, key, relight, simulate, caption, mix and export are all registered commands, and the MCP server’s tool list is generated from that same registry. There is no feature a human can reach that an AI cannot.

The target is the surface of CapCut, After Effects, Premiere and DaVinci Resolve in one engine: editing, motion graphics, VFX, tracking and pro color. It is an early engine with honest tiers. FEATURES.md lists what is solid, what is beta and what is not built.

Capabilities

327 registered tools in 14 groups (full list below):

Architecture

• crates/kimo-core holds the project model, keyframes, the command registry, tool groups, the CPU renderer, effects, text, audio, tracking and color.
• crates/kimo-mcp is the MCP stdio server. Its tool list is generated from the registry.
• kimo is a command line client for the same tools. The fuzz runner and the schema come from the same registry too.
• Rendering and decoding: the renderer is CPU only. GPU code is off by default with a CPU fallback. Decode, encode and probing go through ffmpeg and ffprobe.

Add a tool to the registry and it appears in the MCP server, the CLI, the fuzz test and the schema. See docs/ARCHITECTURE.md and docs/EXTENDING.md.

Principles

• MCP first. Every tool is callable by name. The default tools/list is grouped so a client does not read every schema up front.
• CPU, small memory. Tuned for a 2 GB machine. A cold release build of the whole workspace took 17 minutes on a shared 2 CPU / 2 GB machine (CARGO_BUILD_JOBS=1).
• Measured, not claimed. Every “better than X” line in FEATURES.md has a stated baseline and a measured number, including the cases where we lost.
• Fuzzed. The v3 notes record 6497 fuzz calls with 0 failures at 327 tools. These numbers come from the project notes. They were not re-run for this README.

Install

Status of prebuilt downloads. The v3.0.0 Linux (.deb and portable tar.gz) and Windows x64 assets are listed on the Releases page once they exist there. Windows x64 is built by a GitHub Actions runner and is not verified until the runner output exists. Until you see assets attached to a release, build from source. Older v1.0.0 downloads are a different, 255-tool build.

Build from source (Linux x86_64 is the tested platform)

Everything in this section was run against a build of the v3 branch.

Prerequisites

• Rust stable (install with rustup) and a C linker (build-essential on Debian/Ubuntu).
• ffmpeg and ffprobe on PATH (sudo apt install ffmpeg; checked with ffmpeg 4.4.2). Decode, encode and probing go through them.
• About 2 GB of RAM is enough to run. The release build is the heavy part: use CARGO_BUILD_JOBS=1 on a small box (measured 17 minutes for a cold release build of the whole workspace on a shared 2 CPU / 2 GB machine).
• Linux x86_64 is the tested platform. Other platforms: see Verification status below.

Build

git clone https://github.com/naman-sharma12345/kimo.git
cd kimo
CARGO_BUILD_JOBS=1 cargo build --release --workspace --bins
ls target/release/kimo target/release/kimo-mcp
target/release/kimo --version          # prints version the version in Cargo.toml and the git commit

kimo-mcp is the MCP server (stdio). kimo is the command line client for the same tools.

Check the MCP server answers

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | target/release/kimo-mcp

The reply contains "serverInfo":{"commit":"...","name":"kimo",...,"version":"the version in Cargo.toml"}.

Client config. Use the absolute path of the binary you just built, for example /home/you/kimo/target/release/kimo-mcp.

• Claude Code: claude mcp add --transport stdio kimo -- /home/you/kimo/target/release/kimo-mcp
• Claude Desktop: add this to claude_desktop_config.json (Settings, Developer, Edit Config) and restart the app. The env block is optional; KIMO_TOOLS=core returns a short tools/list.

{
  "mcpServers": {
    "kimo": {
      "command": "/home/you/kimo/target/release/kimo-mcp",
      "args": [],
      "env": { "KIMO_TOOLS": "core" }
    }
  }
}

• Cursor: put the same block in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), then switch the server on in Cursor’s MCP settings.
• Generic MCP client (stdio): command = the absolute path, no arguments, optional env as above. Any client that registers a stdio server by command and uses the mcpServers shape takes the block as is.

The server itself (launch, initialize, tools/list) is verified on this build; the client config file locations come from each client’s docs, not from a run of those apps here.

Codex and OpenCode use the formats shown under “Setup” below with the same path. KIMO_TOOLS=core (env var on the server entry) shrinks tools/list; see “Tool list profiles” below.

Quickstart with the CLI. State lives in a project file (--project p.kimo, created on first use). Every command below ran against this build; replace the media path with your own file.

K=target/release/kimo
$K -q call add_track --project p.kimo                                  # prints {"track_id":"track1"}
$K -q call import_media --project p.kimo --args '{"path":"/abs/path/in.mp4"}'     # returns asset_id, e.g. asset2
$K -q call add_clip --project p.kimo --args '{"track_id":"track1","source_type":"media","asset_id":"asset2","start":0,"duration":3}'
$K -q call add_title --project p.kimo --args '{"track_id":"track1","style":"lower_third","text":"Hello kimo","start":0.5,"duration":2}'
$K -q call render_frame --project p.kimo --args '{"time":1,"path":"/tmp/f.png"}'  # look at one frame
$K -q call describe_frame --project p.kimo --args '{"time":1}'                    # numbers instead of pixels: stats, histogram, clipping, visible clips
$K -q call contact_sheet --project p.kimo --args '{"path":"/tmp/sheet.png","times":[0,1,2]}'
$K export p.kimo out.mp4                                               # render the timeline
$K tools search "color grade"                                          # find tools by words
$K tools describe add_clip                                             # argument schema of one tool

Ids (track1, asset2) are what the previous call returned, so read them from the output. export checks free memory first and refuses with a clear message when the frame would not fit; set KIMO_MEM_MB to override its budget. Exit codes: 0 ok, 1 tool error, 2 usage, 3 preflight failed. kimo --help lists every subcommand.

Setup: add kimo to your AI client

kimo is a local MCP server that speaks over stdin/stdout (the “stdio” transport). There is nothing to start by hand: your client launches kimo-mcp itself. You only need the path to the binary.

1. Get the binary (build from source, see Install above) and put it somewhere stable, for example:

mkdir -p ~/.local/bin && cp /path/to/kimo/target/release/kimo-mcp ~/.local/bin/
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ~/.local/bin/kimo-mcp

The second command should print a JSON reply containing "serverInfo":{"name":"kimo". Install ffmpeg and ffprobe too (sudo apt install ffmpeg, or your package manager).

2. Add it to your client. Replace /home/you/.local/bin/kimo-mcp with your absolute path. Config formats below were checked against each client’s public docs on 2026-10-11; client configs change, so if one fails, check the linked page.

Claude Code

(docs)

claude mcp add --transport stdio kimo -- /home/you/.local/bin/kimo-mcp

Add --scope user to make it available in every project, or --scope project to write it to a shared .mcp.json. Check with claude mcp list, or type /mcp inside Claude Code. The same thing as a .mcp.json file in your project:

{ "mcpServers": { "kimo": { "command": "/home/you/.local/bin/kimo-mcp", "args": [] } } }

OpenAI Codex (CLI and IDE extension)

(docs)

codex mcp add kimo -- /home/you/.local/bin/kimo-mcp

Or edit ~/.codex/config.toml (or .codex/config.toml in a trusted project):

[mcp_servers.kimo]
command = "/home/you/.local/bin/kimo-mcp"

Cursor

(docs)

Create ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{ "mcpServers": { "kimo": { "command": "/home/you/.local/bin/kimo-mcp", "args": [] } } }

Then open Cursor’s MCP settings and switch the kimo server on.

OpenCode

(docs)

Put this in opencode.json in your project, or in ~/.config/opencode/opencode.json for all projects. Note that OpenCode takes command as a list and uses type: "local":

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kimo": { "type": "local", "command": ["/home/you/.local/bin/kimo-mcp"], "enabled": true }
  }
}

Any other MCP client

kimo is a standard MCP stdio server (protocol 2024-11-05, initialize, tools/list, tools/call). Any client that can register a stdio server by command works: give it the absolute path to kimo-mcp and no arguments. Many clients use the mcpServers JSON shape shown for Cursor; some (for example Zed) use a different key, so check your client’s MCP docs for the exact file and format. Only the four clients above were checked against their docs.

Windows: use the path to kimo-mcp.exe (the installer puts it in %LOCALAPPDATA%\\Programs\\kimo\\bin; in JSON write backslashes doubled, see the Windows guide). The configs above are the same except for the path; the Claude Code, Codex, Cursor and OpenCode formats were checked on their docs, not tested on Windows here. macOS: build from source (below) and use the path to target/release/kimo-mcp.

3. Try it. Ask your assistant: “Use kimo to import /path/to/clip.mp4, add a title, and render a frame.” Or drive it yourself with the Python client in examples/mcp_client.py.

Tool list profiles

KIMO_TOOLS picks what tools/list returns. Every tool can be called by its own name under every profile.

Entries and sizes were measured on the v3.0.0 static Linux release build (initialize then tools/list, compact JSON, no client). The 329 in flat is the 327 registry tools plus two discovery tools, search_tools and kimo_describe. kimo_enable_group is listed in grouped and core but not in flat. The 327 count in the badge and the tool listing below is the registry (golden_registry.txt, 327 lines). search_tools(query, limit=8, group?) returns ranked tools, effects and transitions with the required args and a call_as hint.

Set it like this: claude mcp add --transport stdio --env KIMO_TOOLS=core kimo -- /home/you/.local/bin/kimo-mcp, or [mcp_servers.kimo.env] KIMO_TOOLS = "core" for Codex. For JSON configs add "env": { "KIMO_TOOLS": "core" } (OpenCode: "environment": { ... }).

How an AI sees the tools

Call a group with {"action": "", "args": {...}}, for example {"name": "vfx3d", "action": "add_scene3d", "args": {...}}. Calling a tool by its own name also works.

Tool listing (327 tools)

This is the list the v3 build registers (read from tools/list of the grouped server plus kimo_describe group=, 327 tools in 14 groups; the grouped tools/list itself shows 14 group tools plus search_tools, kimo_describe, kimo_enable_group). kimo --version and kimo_info report the workspace version, which is 3.0.0 from this release. Get any tool’s arguments with kimo tools describe or kimo_describe, and find tools by words with search_tools.

Verification status

• Registry: 327 tools. The v3.0.0 static build lists 329 entries in flat mode: those 327 plus search_tools and kimo_describe. The golden registry file crates/kimo-core/tests/golden/golden_registry.txt has 327 lines.
• Fuzz: 6497 calls, 0 failures, as recorded in the v3 notes. Not re-run for this README.
• Windows x64: unverified until a GitHub Actions runner has produced and smoke-tested the installer and ZIP.
• macOS: no binaries; build from source.
• Per-feature limits and change notes: docs/DEV_NOTES.md. Feature tiers: FEATURES.md. Plans: ROADMAP.md.

Contributing and the README rule

The README is updated with every product change. If a change adds, removes or regroups tools, or ships a new proof, the same commit updates this file.

MIT licensed.