Skip to main content
Glama
README.md
# d2v — doc2video CLI and MCP server

[![npm](https://img.shields.io/npm/v/doc2video)](https://www.npmjs.com/package/doc2video)
[![License: MIT](https://img.shields.io/npm/l/doc2video)](./LICENSE)
[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=doc2video&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRvYzJ2aWRlbyIsIm1jcCJdfQ==)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_server-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=doc2video&config=%7B%22name%22%3A%22doc2video%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22doc2video%22%2C%22mcp%22%5D%7D)

Point `d2v` at a folder of documents and photos and it makes a narrated, AI-produced video on
[doc2video.io](https://doc2video.io). Drive it yourself, or let Claude or ChatGPT (Codex) drive it
for you — either through the CLI or as an MCP server.

```bash
d2v create "Spring Open House" ./open-house --duration 1m --aspect 9:16 \
  --direction "Warm and inviting, finish on the garden" --build --wait
```

## Install

Requires Node.js 18.18+.

```bash
npm install -g doc2video     # installs the `d2v` (and `doc2video`) command
```

Or run it without installing: `npx doc2video <command>`.

## Log in

```bash
d2v login
```

Your browser opens doc2video. Sign in (or sign up), check the code matches your terminal, click
**Approve** — done. The key is saved to `~/.doc2video/config.json` and shows up on the dashboard's
API page, where you can revoke it. No browser on this machine? `d2v login --no-browser` prints the
link to open anywhere.

Agents use two steps so they can show you the link: `d2v login --start --json` (returns the link
and code), then `d2v login --wait` after you approve. Over MCP, the `d2v_connect_account` tool does
the same.

You can also paste a key created on the API page (`d2v login --key d2v_…`) or set
`DOC2VIDEO_API_KEY`. To target another server (e.g. local dev) use `--url http://localhost:3000`
or `DOC2VIDEO_URL`.

## What goes in the folder

| Kind | Formats | How it's used |
|------|---------|---------------|
| Documents | PDF, DOCX, PPTX, Markdown, TXT, CSV, JSON | The story: the script is written from them |
| Photos | JPG, PNG, WebP, HEIC (iPhone) | Shown to the scriptwriter and **featured in scenes** |

Folders are scanned recursively (hidden files skipped). Legacy `.doc`/`.ppt`/Keynote/Pages files
are skipped with a hint to convert them. A photos-only folder works too — the story is built from
the photos and your creative direction. With no files at all, use `--draft "description"`.

Photos are used **as-is** by default — cropped to the video's shape, and free as still or Ken
Burns scenes (you only pay for AI work, e.g. an AI video clip made from the photo). Use
`--photos restyle` to have AI polish them into cinematic keyframes while keeping the real subject,
or set it per scene with `d2v scene <p> <n> --photo-treatment restyle`.

## Workflow

```bash
d2v create "Name" ./folder [settings] --build --wait   # storyboard: script → keyframes → narration → preview
d2v show <project>                                     # scenes, narration, preview URL, next steps
d2v pull <project>                                     # keyframes + storyboard.md to a local folder

# steer, scene by scene
d2v keyframe  <p> 3 "warmer light, show the sign"      # edit the image
d2v keyframe  <p> 3 --fresh                            # brand-new image
d2v narration <p> 3 --prompt "shorter and punchier"    # AI rewrite + new voice-over
d2v narration <p> 3 --text "Exact words."              # exact text + new voice-over
d2v scene     <p> 3 --engine veo3                      # still | kenburns | runway | veo3
d2v scene     <p> 3 --photo IMG_2041.jpg               # feature a photo (or --photo none)
d2v run       <p> preview --wait                       # refresh the preview video

# finish (costs money — you pay in the browser)
d2v estimate <p>
d2v buy <p> --open          # or: d2v buy <p> --credits, or: d2v redeem <p> CODE
d2v produce <p> --wait      # AI clips → final assembly
d2v download <p>
```

### Free storyboards and credits

Each day you get **2 free storyboards** and 20 scene redos on unpaid projects. After that, a
storyboard costs **$0.50 from prepaid credits** — pass `--use-credits` to `create --build`, `build`
or `run` to confirm (without it the command stops and tells you the price). Credits also unlock
finished videos: `d2v buy <p> --credits`.

```bash
d2v credits                 # balance, free storyboards left today, recent activity
d2v credits add 10 --open   # top up $5, $10 or $25 in the browser
```

Projects can be named by id, 8-character id prefix, or exact name. `d2v help <command>` shows
every option; `d2v guide` prints the full workflow guide.

**Settings** (on `create` and `set`): `--duration auto|30s|1m|2m|5m|10m`, `--aspect 9:16|16:9`,
`--direction`, `--voice` (see `d2v voices`), `--stability`, `--photos original|restyle`,
`--consistency`/`--no-consistency`, `--client`, `--email`, `--phone`, `--website`.

### Long-running steps

Everything runs on doc2video's servers; a storyboard takes several minutes and final production
longer. `--wait` blocks with progress on stderr, and Ctrl+C only stops the waiting — the work
continues. Pick it back up with `d2v wait <project>`. Steps can be chained on the server, so a
`build` keeps going even if your terminal closes.

### Scripting and agents

Add `--json` to any command for machine-readable output on stdout (progress stays on stderr).
Exit codes: `0` ok, `1` error, `2` usage error, `3` payment required, `4` `--wait` timed out,
`5` rate limit or daily free limit reached.

## Use it from Claude or ChatGPT

### Hosted MCP server (nothing to install)

doc2video also runs the MCP server for you at **`https://doc2video.io/mcp`**. Add it as a custom
connector and sign in with your doc2video account when asked (OAuth — no keys to copy):

- **Claude** (claude.ai, Desktop, mobile): Settings → Connectors → Add custom connector, URL
  `https://doc2video.io/mcp`.
- **Claude Code:** `claude mcp add --transport http doc2video https://doc2video.io/mcp`, then run
  `/mcp` to sign in.
- **ChatGPT:** add a connector with the server URL `https://doc2video.io/mcp` (developer mode) and
  OAuth sign-in.
- **Cursor, VS Code and other clients:** a remote server entry such as
  `{ "doc2video": { "url": "https://doc2video.io/mcp" } }` (VS Code: `"type": "http"`).

The hosted server has the same tools, but it can't see your computer's files: give it text, public
links (PDFs, Word and PowerPoint files, photos, web pages), or add files on the project page it
links to. To work from local folders, use the CLI or `d2v mcp` below. Connected apps are listed,
and can be disconnected, on your dashboard's API page.

### Claude Code / Codex CLI (shell)

Both can simply run `d2v`. Open a terminal agent in the folder with your files and ask, e.g.
*"Make a 60-second vertical video from this folder with doc2video, show me the storyboard, and
punch up the opening."* For better results, install the agent instructions:

- **Claude Code:** copy `agents/SKILL.md` to `~/.claude/skills/doc2video-cli/SKILL.md`
- **Codex CLI:** append `agents/AGENTS.md` to `~/.codex/AGENTS.md` (or the folder's `AGENTS.md`)

Both files ship with the package — find them under `$(npm root -g)/doc2video/agents/`.

### MCP (Claude Desktop, Claude Code, Codex, any MCP client)

`d2v mcp` runs an MCP server over stdio with tools for the whole workflow — including
`d2v_view_storyboard`, which returns the keyframe images so the model can actually see the
storyboard and give visual feedback. It's listed in the official
[MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.doc2video/d2v`.

The API key below is optional: without one, the `d2v_connect_account` tool gives you a link to
sign in (or sign up) in your browser, and remembers the key.

**Cursor / VS Code** — use the buttons at the top of this page.

**Claude Code**

```bash
claude mcp add doc2video -- npx -y doc2video mcp
# or with a key from doc2video.io/dashboard/api-keys:
claude mcp add doc2video -e DOC2VIDEO_API_KEY=d2v_xxx -- npx -y doc2video mcp
```

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "doc2video": {
      "command": "npx",
      "args": ["-y", "doc2video", "mcp"],
      "env": { "DOC2VIDEO_API_KEY": "d2v_xxx" }
    }
  }
}
```

**Codex CLI** — `~/.codex/config.toml`:

```toml
[mcp_servers.doc2video]
command = "npx"
args = ["-y", "doc2video", "mcp"]
env = { DOC2VIDEO_API_KEY = "d2v_xxx" }
```

With a global install you can use `"command": "d2v", "args": ["mcp"]` instead of `npx`.

**ChatGPT (web/desktop):** ChatGPT connects only to *remote* MCP servers, so use the hosted server
above. Use Codex CLI for local folders.

## REST API

The CLI is a thin client over the doc2video REST API — see [API.md](./API.md) to call it directly.

## Development

```bash
npm install
npm run build      # compile to dist/
npm test           # build + end-to-end tests against a mock API (no network)
npm link           # use your local build as `d2v`
```

Releases are published from GitHub Actions when a `v*` tag is pushed: to npm (with provenance)
and to the MCP Registry. Issues and pull requests are welcome at
[github.com/doc2video/cli](https://github.com/doc2video/cli).

## License

The CLI and MCP server are [MIT licensed](./LICENSE). They're a client for the hosted
doc2video service at [doc2video.io](https://doc2video.io), which has its own
[terms](https://doc2video.io/terms).