Axcel MCP

Use Axcel Studio 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.

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

• Requirements

• Quick start

• Connect your AI agent

• Signing in

• Using it

• Film studio skill

• Tools

• Configuration

• Where your files go

• Troubleshooting

• Privacy and security

• Updating and uninstalling

• Development

Related MCP server: media-gen-mcp

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.

• 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

Works on macOS, Windows and Linux.

Quick start

There are three steps. Each takes about a minute.

1. Install

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

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 ….

2. Connect your AI agents

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 for the agents that support skills.

3. Sign in to Axcel (once)

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.

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.

Add to ~/.codex/config.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.

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

OpenCode 2.x:

{
  "$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:

{
  "$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
    }
  }
}

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

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>.

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

{
  "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).

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

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

Quit Claude Desktop completely and reopen it.

• 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:

  { "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/.

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.

1. Sign in to axcel.cloud 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:

   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.

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.

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 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. It is the production method behind several 5–9 minute AI films, written down step by step for any agent.

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 (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

Every parameter is described in docs/TOOLS.md. The Axcel web API this is built on is documented in 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.

Where your files go

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

Troubleshooting

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.

Updating and uninstalling

Update:

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

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