# Axcel MCP

**Use [Axcel Studio](https://axcel.cloud/a/7968186774) from any AI agent.** Generate AI videos and images with your own Axcel account from Claude Code, Codex, OpenCode, Hermes Agent, Cursor, Claude Desktop, Windsurf, Gemini CLI, VS Code, or any other client that supports the [Model Context Protocol](https://modelcontextprotocol.io).

```text
You:    Make an 8-second 16:9 video with sound of waves at sunset, then a matching 1:1 thumbnail.
Agent:  axcel_generate_video → axcel_job_status → saved ~/Downloads/axcel/seedance-2-5-1a2b3c4d.mp4
        axcel_generate_image → saved ~/Downloads/axcel/nano-banana-pro-5e6f7a8b.png
```

> **Unofficial project.** It is not made by, affiliated with, or endorsed by Axcel. It drives axcel.cloud through the same web API the site uses, with **your own account and plan**. That API is private and may change without notice. Use it for normal personal use and follow Axcel's terms of service. The axcel.cloud links in this README are the maintainer's affiliate link; the MCP itself adds no tracking.

## Contents

- [What it can do](#what-it-can-do)
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Connect your AI agent](#connect-your-ai-agent)
- [Signing in](#signing-in)
- [Using it](#using-it)
- [Film studio skill](#film-studio-skill)
- [Tools](#tools)
- [Configuration](#configuration)
- [Where your files go](#where-your-files-go)
- [Troubleshooting](#troubleshooting)
- [Privacy and security](#privacy-and-security)
- [Updating and uninstalling](#updating-and-uninstalling)
- [Development](#development)

## What it can do

- **Text to video**, for example with Seedance 2.0 / 2.5 or Veo 3.1 Fast. Choose duration, resolution and aspect ratio, and optionally generate **sound and speech** in English, Malay or Indonesian.
- **Image to video:**
  - animate a start frame
  - go from a start frame to an end frame
  - guide the video with **reference images** (`@Image1`, `@Image2` …) plus optional reference video/audio, if your plan includes it
- **Image generation**, for example with Nano Banana Pro or Seedream 5.0 Pro, optionally from up to 4 reference images.
- **Seamless multi-scene films.** Each scene starts from the last frame of the previous one, then all clips are joined into one MP4. This runs in the background.
- **Results:** downloads with a JSON manifest (SHA-256, media info), visual previews for the agent, frame extraction, and joining clips with optional crossfades.
- **Your Axcel account:** status, plan limits, history, Library, folders and ZIP downloads.
- **Film studio skill:** a complete, tested workflow that takes the agent from your idea to a finished film. It always asks you the key choices first (landscape or portrait, length, voice, HeyGen or ElevenLabs for sound, budget). Story, reference images, scenes with dialogue QA, upscaling, a **HyperFrames** edit, mastering and subtitles are separate phases. See [Film studio skill](#film-studio-skill).
- **Safe by default:**
  - Generations and deletions need an explicit `confirm: true`.
  - Slow jobs are polled, never resubmitted.
  - It never makes purchases.

The model list always comes live from Axcel, so new models show up without an update.

## Requirements

| | |
|---|---|
| **Node.js 20 or newer** | [nodejs.org](https://nodejs.org) (LTS). Check with `node -v`. |
| **Google Chrome** (or Edge, Brave, Chromium) | Used once to open the Axcel sign-in window. Nothing extra is downloaded. |
| **An Axcel Studio account with a plan** | Sign up at [axcel.cloud](https://axcel.cloud/a/7968186774). Generations use your plan and credits. |
| **ffmpeg** *(optional, recommended)* | Needed for chaining scenes, joining clips, frame extraction and previews. macOS: `brew install ffmpeg` · Windows: `winget install Gyan.FFmpeg` · Debian/Ubuntu: `sudo apt install ffmpeg` |

Works on macOS, Windows and Linux.

## Quick start

There are three steps. Each takes about a minute.

### 1. Install

```bash
git clone https://github.com/aredamz/axcel-mcp.git
cd axcel-mcp
npm install
```

<details>
<summary>Or install it as a global command</summary>

```bash
npm install -g github:aredamz/axcel-mcp
```

With a global install, the commands below are `axcel-mcp setup`, `axcel-mcp login`, `axcel-mcp doctor` and so on, instead of `npm run …`.
</details>

### 2. Connect your AI agents

```bash
npm run setup
```

This finds the AI agents installed on your computer and registers the `axcel` MCP server with them:

- Claude Code
- Codex
- OpenCode
- Hermes Agent
- Cursor
- Claude Desktop
- Windsurf
- Gemini CLI
- VS Code

It shows what it found and asks before changing anything. It backs up each config file the first time it edits it. It also installs the [film studio skill](#film-studio-skill) for the agents that support skills.

### 3. Sign in to Axcel (once)

```bash
npm run login
```

1. A browser window opens on axcel.cloud.
2. Click **Continue with Google** and sign in with the Google account that has your Axcel plan.
3. The window closes by itself when you are signed in.

The session is shared by every agent on your computer, so you only do this once (Axcel sessions last about 30 days).

Restart your agent and ask it: **"Check my Axcel status."** That's it.

> Tip: `npm run doctor` checks everything at once: Node, browser, ffmpeg, network, session and which agents are connected.

## Connect your AI agent

`npm run setup` does this for you. To do it by hand, or for a client not listed, use the snippets below.

In every snippet, replace `/ABSOLUTE/PATH/TO/axcel-mcp` with the folder you cloned. If your client cannot find `node`, use its full path, for example `/usr/local/bin/node` or `C:\Program Files\nodejs\node.exe` (in JSON, write backslashes as `\\`). `npm run setup -- --print` prints all snippets with your real paths filled in.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add -s user axcel -- node /ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js
```

`-s user` makes it available in every project. Check with `claude mcp list`.
</details>

<details>
<summary><b>Codex</b> (CLI, IDE extension and desktop app)</summary>

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.axcel]
command = "node"
args = ["/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"]
startup_timeout_sec = 30
tool_timeout_sec = 600
```

Check with `codex mcp list`.
</details>

<details>
<summary><b>OpenCode</b></summary>

Add to `~/.config/opencode/opencode.json`, or to `opencode.json` in a project.

OpenCode 2.x:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "axcel": {
        "type": "local",
        "command": ["node", "/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"]
      }
    }
  }
}
```

OpenCode 1.x:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "axcel": {
      "type": "local",
      "command": ["node", "/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"],
      "enabled": true,
      "timeout": 600000
    }
  }
}
```
</details>

<details>
<summary><b>Hermes Agent</b></summary>

Add to `~/.hermes/config.yaml`, then run `/reload-mcp` inside Hermes:

```yaml
mcp_servers:
  axcel:
    command: "node"
    args: ["/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"]
    timeout: 600
    connect_timeout: 60
```

Hermes shows the tools as `mcp_axcel_<tool>`.
</details>

<details>
<summary><b>Cursor</b></summary>

Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "axcel": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"]
    }
  }
}
```

Cursor limits the total number of MCP tools. If you hit the limit, expose fewer tools with `"env": { "AXCEL_TOOLS": "core,sequence" }` (see [Configuration](#configuration)).
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings → Developer → Edit Config, or edit the file directly:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "axcel": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"]
    }
  }
}
```

Quit Claude Desktop completely and reopen it.
</details>

<details>
<summary><b>Windsurf</b> · <b>Gemini CLI</b> · <b>VS Code</b> · others</summary>

- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`, same `mcpServers` block as Cursor.
- **Gemini CLI:** `~/.gemini/settings.json`, same `mcpServers` block. You can add `"timeout": 600000`.
- **VS Code (Copilot agent mode):** run `code --add-mcp '{"name":"axcel","type":"stdio","command":"node","args":["/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"]}'`, or put this in `.vscode/mcp.json`:

  ```json
  { "servers": { "axcel": { "type": "stdio", "command": "node", "args": ["/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js"] } } }
  ```

- **Any other MCP client** (Cline, Roo Code, Zed, Continue, LM Studio, Goose …): add a **stdio** server with command `node` and argument `/ABSOLUTE/PATH/TO/axcel-mcp/bin/axcel-mcp.js`.

More ready-made files are in [`examples/`](examples/).
</details>

## Signing in

axcel.cloud signs you in with Google (plus a Cloudflare check). There is no password API, so this MCP opens a **real browser window** with its own profile, and **you sign in yourself**. Only the resulting session cookie is saved, in an owner-only file on your computer. Your password and 2FA codes never pass through this code or through the AI agent.

There are three ways to start:

- **Terminal:** run `npm run login` (or `axcel-mcp login`).
- **Through your agent:** say *"Sign in to Axcel"*. The agent calls `axcel_login_begin`, you sign in in the window, reply "done", and the agent calls `axcel_login_complete`.
- **Check the result:** `npm run status` shows the account, plan, expiry and limits.

<details>
<summary><b>Cookie file</b> (if the window can't be used, or Google blocks it)</summary>

1. Sign in to [axcel.cloud](https://axcel.cloud/a/7968186774) in your normal browser.
2. Open DevTools (F12) → **Network**. Reload the page and click any request to `axcel.cloud/api/...`.
3. Under **Request Headers**, copy the whole value of `cookie`, and paste it into a text file, for example `~/axcel-cookie.txt`.
4. Run:

   ```bash
   npm run login -- --cookie-file ~/axcel-cookie.txt --delete-file
   ```

   Or ask your agent to call `axcel_login_import_cookie_file` with the file path.

A JSON export from a cookie extension and a Netscape `cookies.txt` file also work. **Never paste cookies into the chat.**
</details>

<details>
<summary><b>Servers without a screen</b> (VPS, Docker, remote Hermes)</summary>

Sign in on a computer with a browser. Then either:

- copy `~/.axcel-mcp/session.json` to the same place on the server, or
- set the environment variable `AXCEL_COOKIE` (the cookie header value) in the MCP server's config.

Treat both like a password.
</details>

To sign out: `npm run logout`. This removes the saved session and the sign-in browser profile. Add `-- --server` to also end the session on axcel.cloud.

## Using it

Just ask your agent in plain language. Some examples:

- *"What can the Axcel MCP do?"*
- *"Check my Axcel status and list the video models."*
- *"Make an 8-second 720p 16:9 video with sound: rain on a café window at night, warm light inside."*
- *"Animate `./poster.png` into a 9:16 video with Veo 3.1 Fast."*
- *"Make a 5-second video that starts at `start.jpg` and ends at `end.jpg`."*
- *"The person in @Image1 walks into the shop in @Image2"*, giving `person.png` and `shop.png` as reference images.
- *"Generate a 1:1 product photo of a red sneaker on white, then turn it into a 5-second video."*
- *"Make a 4-scene seamless short film about a paper boat's journey, 10 seconds per scene, and join it into one MP4 in this project's `renders/` folder."*
- *"Save that result to my Axcel Library in a folder called Campaign."*

### How a generation runs

1. The agent reads the live options with `axcel_list_models`. Only the durations, resolutions and ratios a model supports are accepted.
2. Files you mention are uploaded automatically. You can use local paths, URLs or Axcel asset IDs. Oversized or unusual images are converted to fit Axcel's limits.
3. The job is submitted and the agent waits up to 40 seconds.
4. If the job is still rendering, the agent polls `axcel_job_status` with the **same** `jobId`. It never resubmits, so you never pay twice for one request.
5. When the job is done, the file is downloaded together with a `.axcel.json` manifest. The agent can look at it with `axcel_view`.

Short clips usually take 1–10 minutes. Long 1080p clips can take much longer.

See [docs/PROMPTING.md](docs/PROMPTING.md) for prompt tips: reference images, dialogue, continuity and multi-scene films.

## Film studio skill

For more than one clip (a short film, a story video for TikTok, a series episode, a trailer), the repository ships a skill: [`skills/axcel-film-studio`](skills/axcel-film-studio/SKILL.md). It is the production method behind several 5–9 minute AI films, written down step by step for any agent.

| Phase | What happens |
|---|---|
| 0–1 Setup & decisions | The agent checks your account and tools, then **asks you the key choices before generating anything**: landscape or portrait (always), platform, length, story, dialogue or narration, language, models, budget, **HeyGen or ElevenLabs** for sound effects/music/voice, subtitles, credits. |
| 2 Story & script | `STORY.md` + a storyboard with timed beats and exact dialogue lines. You approve it. |
| 3 Reference images | Character sheets, face close-ups and empty locations for consistent faces and places. You approve the look. |
| 4 Scenes | Generated with retries; every job id is recorded, so nothing is ever paid for twice. The agent tells you the job count first. |
| 5 Download & QA | Contact sheets, and Whisper dialogue checks (did the model say the line?). You review the picks. |
| 6 Upscale | Optional Real-ESRGAN pass that keeps the orientation. |
| 7 Edit (HyperFrames) | Clips, title/act/end cards, stamps, HUDs, grade, music carved under dialogue, SFX and narration from HeyGen or ElevenLabs. |
| 8–10 Master, subtitles, wrap-up | −16 LUFS master, subtitle files on one sequential track (no overlapping cues), README. |

It includes:
- helper scripts (`produce.mjs`, `dialogue_qa.py`, `hf_build.py`, `subtitles.py` …)
- templates
- two worked examples: a landscape dialogue film and a portrait narrated TikTok short

**Install:**
- `npm run setup` already installs it for Claude Code, Codex (`~/.agents/skills`), OpenCode and Hermes.
- Or install it separately with `npm run skill` (`axcel-mcp skill install`).

**Use:** ask your agent *"Make a 2-minute horror short with Axcel"* or *"Use the axcel-film-studio skill"*.

Clients without skills support (Cursor, Claude Desktop, VS Code, Windsurf …) get the same guide through the MCP:
- the tool `axcel_film_guide`
- the prompt `film-studio`, which shows up in Claude Code as `/mcp__axcel__film-studio`

Optional tools the skill asks before using:
- [HyperFrames](https://hyperframes.heygen.com) (`npx hyperframes`) for the edit
- the HeyGen CLI or an ElevenLabs API key for sound
- `faster-whisper` for dialogue QA and subtitles
- Real-ESRGAN for upscaling

## Tools

| Group | Tools |
|---|---|
| Account & sign-in | `axcel_help`, `axcel_film_guide`, `axcel_status`, `axcel_login_begin`, `axcel_login_complete`, `axcel_login_diagnose`, `axcel_login_import_cookie_file`, `axcel_logout`, `axcel_list_models`, `axcel_billing_plans` |
| Generate | `axcel_generate_video`, `axcel_generate_image`, `axcel_job_status`, `axcel_active_jobs`, `axcel_download_job`, `axcel_view`, `axcel_upload` |
| History | `axcel_history_list`, `axcel_history_get`, `axcel_history_delete` |
| Library | `axcel_library_list`, `axcel_library_save_job`, `axcel_library_delete`, `axcel_library_move`, `axcel_folder_list`, `axcel_folder_create`, `axcel_folder_rename`, `axcel_folder_delete`, `axcel_folder_download_zip` |
| Multi-scene & editing | `axcel_sequence_start`, `axcel_sequence_status`, `axcel_sequence_list`, `axcel_extract_frame`, `axcel_concat_videos` |

Every parameter is described in [docs/TOOLS.md](docs/TOOLS.md). The Axcel web API this is built on is documented in [docs/API.md](docs/API.md).

## Configuration

Everything works without configuration. To change a default, set an environment variable in your agent's MCP config (the `env` / `environment` block), or pass it to setup, for example `npm run setup -- --env AXCEL_LANGUAGE=ms`.

| Variable | Default | What it does |
|---|---|---|
| `AXCEL_OUTPUT_DIR` | `~/Downloads/axcel` | Where results are saved, unless a tool call gives `outputDirectory`. |
| `AXCEL_LANGUAGE` | `en` | Accent of generated speech: `en`, `ms` (Malay) or `id` (Indonesian). |
| `AXCEL_WAIT_SECONDS` | `40` | How long one tool call waits for a job before returning its `jobId` for polling. Keep it under your client's tool timeout. |
| `AXCEL_TOOLS` | `all` | Tool groups to expose: `core` (always on), `history`, `library`, `sequence`. Example: `core,sequence`. |
| `AXCEL_MCP_DATA_DIR` | `~/.axcel-mcp` | Session, job records and the sign-in browser profile. |
| `AXCEL_BROWSER_EXECUTABLE` | auto-detected | Browser for the sign-in window (any Chromium-based browser). |
| `AXCEL_COOKIE` | – | Session cookie header for machines without a browser. Treat it like a password. |
| `FFMPEG_PATH`, `FFPROBE_PATH` | `ffmpeg`, `ffprobe` | Custom ffmpeg location. |
| `AXCEL_BASE_URL` | `https://axcel.cloud` | Only for testing. |

## Where your files go

| What | Where |
|---|---|
| Videos and images | `~/Downloads/axcel/` (or `AXCEL_OUTPUT_DIR` / `outputDirectory`). Each result has a `.axcel.json` manifest next to it. |
| Multi-scene films | `~/Downloads/axcel/<film-name>/`, with each scene plus `<film-name>-final.mp4`. |
| Session, job records, browser profile | `~/.axcel-mcp/`. This is private: never share or commit it. |

Axcel deletes results after **7 days** and Library files after **14 days**. Anything downloaded stays on your computer.

## Troubleshooting

| Problem | Fix |
|---|---|
| Agent doesn't show the Axcel tools | Restart the agent after `npm run setup`. Run `npm run doctor` and check the "Registered with" line. Re-run `npm run setup` after moving the folder or switching Node versions. |
| `login_required` / "session expired" | Run `npm run login` again, or ask the agent to sign in. |
| No sign-in window appears | Install Google Chrome, or set `AXCEL_BROWSER_EXECUTABLE`. On a headless server, use the cookie file or `AXCEL_COOKIE`. |
| Google says the browser is not secure | Try `axcel_login_begin` with `restart: true`, or use the [cookie file](#signing-in) method. |
| "sign-in window is already open" | Another agent or terminal has the window open. Finish signing in there, or close it. |
| A job takes very long | That's normal for long or 1080p clips. The agent keeps polling the same `jobId`. You can also check `axcel_active_jobs`. |
| `ffmpeg_missing` | Install ffmpeg (see [Requirements](#requirements)) and restart the agent. Generation itself works without it. |
| "Model is unavailable" / a job failed on Axcel | Provider-side failure. Try again later, or pick another model. The MCP never retries automatically, because a retry is a new paid job. |
| `credits_exhausted` / `payment_required` | Your Axcel plan or credits do not cover the request. Check your plan on axcel.cloud. |
| Tool call times out in Codex | `npm run setup` sets `tool_timeout_sec = 600`. If you configured Codex by hand, add it, or lower `AXCEL_WAIT_SECONDS`. |
| Something else changed on axcel.cloud | The web API is private and can change. Please open an issue with the error message. |

## Privacy and security

- **No telemetry.** The server only talks to `axcel.cloud`, plus any URL you ask it to fetch as an input image.
- **Your session cookie is only sent to axcel.cloud**, never to other hosts. It is stored in `~/.axcel-mcp/session.json`, readable by your user account only.
- **The AI agent never sees your password, 2FA codes or cookies.** Tool results show only your Axcel display name, plan and limits.
- Generation and deletion tools need `confirm: true`, and the agent is told to use it only for what you asked. Tool annotations mark read-only and destructive tools, so clients can ask you before running them.
- **No purchases.** There are no payment, admin, affiliate or support-message endpoints in this code.
- Config files are backed up (`*.backup-before-axcel-mcp`) before `setup` first edits them.

Found a security problem? See [SECURITY.md](SECURITY.md).

## Updating and uninstalling

**Update:**

```bash
cd axcel-mcp
git pull
npm install
```

Or, for a global install: `npm install -g github:aredamz/axcel-mcp`.

**Uninstall:**

1. Run `npm run logout`.
2. Remove the `axcel` entry from your agents. For Claude Code that's `claude mcp remove axcel -s user`; for the others, delete the `axcel` block from the config files listed above.
3. Remove the skill links with `npm run skill -- remove`.
4. Delete the `axcel-mcp` folder and `~/.axcel-mcp`.

## Development

```bash
npm test          # offline tests: request building, config writers, image parsing, MCP server over stdio
npm run smoke     # live check against your signed-in account (read-only; add -- --image to also generate one image)
npm run doctor    # environment check
```

Project layout:

```
bin/axcel-mcp.js   entry point (MCP server on stdio, or CLI commands)
skills/            axcel-film-studio: the film-production skill (SKILL.md, references, scripts, templates, examples)
src/server.js      MCP tools
src/api.js         axcel.cloud API client
src/requests.js    builds and validates /api/generate requests against the live catalog and plan
src/auth.js        sign-in window, session and cookie import
src/media.js       ffmpeg helpers: upload limits, frames, joining clips, previews
src/setup.js       client config writers (Claude Code, Codex, OpenCode, Hermes, Cursor, ...)
src/cli.js         setup / login / status / doctor / logout
docs/              tool reference, API notes, prompting guide
```

Contributions are welcome. Please run `npm test` before opening a pull request, and never commit anything from `~/.axcel-mcp`.

## License

[MIT](LICENSE)