Ads Optimiser MCP server

Connects Claude (Desktop, Code, or any MCP client) to Ads Optimiser so you can generate TikTok ad images and videos from a chat, using files on your own computer.

Sign-in is SSO, not keys. The first connection starts an OAuth device flow (RFC 8628): Claude shows you a URL and a short code, you approve in a browser where you are already signed in to Ads Optimiser, and a workspace-scoped token is delivered back automatically. Nothing is typed, pasted, or stored in any config file.

Setup

Requires Node.js 18.17 or later. The package is a single self-contained file with no dependencies, so npx has one small download to make and starts in well under Claude Desktop's start-up limit.

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude Desktop from the system tray:

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

On Windows, if npx fails to launch, use "command": "cmd", "args": ["/c", "npx", "-y", "@cintelisai/adsoptimiser-mcp@latest"].

Troubleshooting on Windows

If Ads Optimiser does not appear in Claude Desktop, or shows as failed:

1. Check the server log at %LOCALAPPDATA%\Claude\Logs\mcp-server-adsoptimiser.log. The Microsoft Store version of Claude Desktop logs there; other installs log to %APPDATA%\Claude\logs. Claude Desktop gives a server about 30 seconds to answer, so a log that ends with the transport closing shortly after initialize means the server started too slowly.

2. Version 0.2.0 and later start in well under a second once downloaded. If you are on an older version, @latest in the config picks up the fix on the next restart.

3. To take npx out of the picture entirely, install the package once and point Claude Desktop at it with node:

   npm install -g @cintelisai/adsoptimiser-mcp
   npm root -g

   npm root -g prints the global folder, for example C:\Users\you\AppData\Roaming\npm\node_modules. Then use:

   {
     "mcpServers": {
       "adsoptimiser": {
         "command": "node",
         "args": ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@cintelisai\\adsoptimiser-mcp\\dist\\server.mjs"]
       }
     }
   }

   A global install does not update itself: run npm install -g @cintelisai/adsoptimiser-mcp again to upgrade.

Claude Code

claude mcp add adsoptimiser -- npx -y @cintelisai/adsoptimiser-mcp@latest

The @latest tag makes npx check for updates on each launch, so you never stay stuck on an old cached copy.

Connecting

In any chat: "connect to Ads Optimiser". Claude will call adsoptimiser_connect and give you a URL and code.

1. Open the URL and sign in to Ads Optimiser if asked.
2. Check the code on the page matches the one Claude showed you. If it does not, do not approve.
3. Choose the workspace this connection should use, then approve. The token only works in that workspace; to use another one later, disconnect and connect again. You need to be a member (not a viewer) of the workspace.
4. Tell Claude you've approved; it calls adsoptimiser_finish_connect and you're connected.

Tools

| Tool | What it does | | --- | --- | | adsoptimiser_connect | Start the SSO device flow | | adsoptimiser_finish_connect | Collect the token after you approve | | adsoptimiser_status | Show the connected user, workspace and role | | adsoptimiser_disconnect | Revoke the token on the server and delete it from this machine | | adsoptimiser_list_models | List image and video models, their options and indicative cost | | adsoptimiser_enhance_prompt | Expand a rough idea into a detailed ad prompt (uses no allowance) | | adsoptimiser_generate_image | Generate an image, with a preview of the result; accepts local reference images (reference_image_paths), URLs, earlier jobs or a saved character_id | | adsoptimiser_generate_video | Start a video; text-to-video, or image-to-video from a local image (source_image_path), URL or earlier job; character_id and script for talking clips | | adsoptimiser_lip_sync | Make the person in a finished clip (a job, a URL or a local video_path) say a new line in a designed voice, lip-synced by Kling | | adsoptimiser_add_overlays | Burn timed text cards or captions into any finished video (a job, a URL or a local video_path), or captions timed to the speech with auto_captions; place text with y, size and max_width | | adsoptimiser_get_job | Status and result URL of one job, with a preview once it is finished | | adsoptimiser_list_jobs | Recent jobs, filterable by status and type; previews with include_thumbnails | | adsoptimiser_list_pipelines | Pipeline templates and saved pipelines | | adsoptimiser_get_pipeline_nodes | The pipeline node catalogue: node types, inputs, outputs, params, graph rules and an example | | adsoptimiser_get_pipeline | A saved pipeline's graph, node count and estimated cost per run | | adsoptimiser_validate_pipeline | Check a pipeline graph: errors by node, node count, estimated cost, whether it needs a prompt (uses no allowance) | | adsoptimiser_save_pipeline | Save a pipeline graph to the workspace, or update a saved one by graph_id, and link to the pipeline editor | | adsoptimiser_run_pipeline | Start a pipeline run from a template, a saved pipeline or an inline graph, optionally with a character_id | | adsoptimiser_get_pipeline_run | Status and results of each pipeline step | | adsoptimiser_list_characters | Saved characters with their images, description, style and voice | | adsoptimiser_get_character | One character with every reference image (previewed) and the job it came from, plus counts of what was made with it, the latest items and the latest voice previews | | adsoptimiser_list_character_assets | Everything made with a character, filterable by type and paged; previews with include_thumbnails; with download_to the finished files and speech mp3s are saved locally | | adsoptimiser_view_image | One image (a job, a media key or a character's reference image) at 768, 1024 or 1536 px, optionally cropped to zoom into a region, for checking detail; with save_to it is also saved locally | | adsoptimiser_create_character | Save a character from 1 to 5 images: local files (image_paths), URLs or finished jobs, with an optional voice (uses no allowance) | | adsoptimiser_update_character | Change a character's name, description, style, voice or images (uses no allowance) | | adsoptimiser_list_voices | xAI preset voices and OpenAI voices, and whether OpenAI voices are available | | adsoptimiser_preview_voice | A short sample in any voice as a playable URL, optionally filed in a character's preview history, and with save_to an mp3 saved locally (uses no allowance) | | adsoptimiser_upload_file | Upload a local image or video and get its hosted URL (uses no allowance) | | adsoptimiser_download_job | Save a finished job's image or video to a local folder | | adsoptimiser_batch_generate | One job per image in a folder (image-to-video or image edit) or per line of a prompts file, up to 10 per call |

Every generation uses your workspace's monthly plan allowance, exactly as in the app. When the allowance runs out, the tools say so and link to Billing (https://app.adsoptimiser.com.au/#/billing) where you can upgrade. Videos also count toward a daily video quota.

Image models

adsoptimiser_generate_image (and adsoptimiser_batch_generate, and a pipeline's generate_image step) takes a model. adsoptimiser_list_models shows what your deployment offers, with sizes and indicative cost.

| Model | Id | Good for | Options | | --- | --- | --- | --- | | Grok Image 2.0 (default) | grok-imagine-image-2.0 | General ad images | quality low (fastest, about 13s), medium or auto (45 to 50s); resolution 1k or 2k; wide ratios such as 21:9 | | Grok Image | grok-imagine-image | The fastest Grok images | No quality | | GPT Image 2.5 Sunburst (precise, fast) | gpt-image-2.5-sunburst | Detailed specs followed exactly, in about 12 seconds | quality low, medium (default), high or auto | | GPT Image 2.5 Flare (fast) | gpt-image-2.5-flare | Quick drafts in about 9 seconds, less precise on detail | quality low, medium (default), high or auto |

When to pick Sunburst: when the image has to match a detailed brief. For example exact colours ("four buttons: green, teal, amber, coral"), exact counts of objects, a character sheet (the same person from set angles, a full-body shot and a close-up), or a thumbnail with layout constraints (a title in the top third, the face on the right, room left for a logo). Grok suits open-ended scenes; Sunburst is the one to use when the details matter.

The GPT Image 2.5 models are OpenAI models, offered only where the deployment has an OpenAI key (otherwise the tools say so and suggest a Grok model). They take aspect_ratio 1:1 (1024x1024), 2:3 or 9:16 (both delivered at 1024x1536), 3:2 or 16:9 (both delivered at 1536x1024), or auto. Any other ratio, and any resolution, is refused on your machine before anything is sent, as is quality high on a Grok model. Up to 5 reference images work with them, the same as Grok, as does character_id. A finished job made by OpenAI shows its provider cost (about US$0.011 at medium quality). Each image uses one image generation from the plan allowance, whichever model makes it.

Automatic fallback. When Grok fails upstream (a 5xx error or a timeout) the deployment retries the image once on GPT Image 2.5 Sunburst, with the same prompt and references. It never retries a refused request or a moderation block, and the retry still counts as one generation. The job's model is then the model that made the image, and adsoptimiser_get_job says what happened, for example "Generated with GPT Image 2.5 Sunburst after Grok failed (500)", or for a job that failed both ways "Grok timed out; retried once on GPT Image 2.5 Sunburst". adsoptimiser_list_jobs marks these jobs too.

Previews: Claude can see the images

Tools attach small preview images (384 px) to their results, so Claude can look at what was generated instead of working from URLs alone: check a new image, pick the best shots of a character sheet, or compare recent results. The include_thumbnails flag controls this per call:

| Tool | Previews | Default | | --- | --- | --- | | adsoptimiser_generate_image | the finished image, when it is ready in time | on | | adsoptimiser_get_job | the finished image, or a video's poster frame | on | | adsoptimiser_get_character | up to 5 reference images | on | | adsoptimiser_list_jobs | up to 6 finished jobs | off | | adsoptimiser_list_character_assets | up to 6 finished images on the page | off |

To keep results small, each preview is at most 600,000 bytes (base64) and one result carries at most 1,500,000 bytes of images; anything over is left out and named in the reply. Videos are previewed only when a poster frame is stored. Reference images hosted elsewhere are not previewed. A preview that fails never fails the tool: the reply says what was not previewed and why. On an Ads Optimiser deployment that predates previews, the reply says the deployment doesn't serve previews yet. Previews use no allowance.

To check detail (colours, small features, text, the views on a character sheet), ask Claude to look closer: adsoptimiser_view_image returns one image at 768, 1024 or 1536 px (default 1024), and its crop zooms into a region given as fractions of the original, for example { x: 0.3, y: 0.5, width: 0.4, height: 0.3 }. Each image is at most 2,000,000 bytes (base64); a larger one is fetched again one size smaller. For characters, separate images per view show far more detail than one sheet holding many views. On an older deployment it says view_image isn't supported yet.

Claude Code limits how large a tool result may be (the MAX_MCP_OUTPUT_TOKENS setting). If a result with several previews is cut off or refused, ask Claude to call the tool with include_thumbnails set to false, or raise that limit.

Building pipelines

A pipeline is a small graph of steps (up to 12 nodes): for example refine a prompt, generate an image, then animate it into a video. Ask Claude to design one, for example "build a pipeline that turns my product photo into three 9:16 videos with different voices". Claude reads the node catalogue with adsoptimiser_get_pipeline_nodes, checks its graph with adsoptimiser_validate_pipeline (which reports problems by node, the estimated cost per run and whether a prompt is needed), then saves it with adsoptimiser_save_pipeline or runs it directly with adsoptimiser_run_pipeline. Saved pipelines open in the app's pipeline editor at https://app.adsoptimiser.com.au/#/pipeline-editor.

Where a graph needs one of your own images (an input_image node), give its local path as the node's image_url (or image_path). The file is checked and uploaded, and the hosted URL is put in its place before the graph is validated, saved or run.

A pipeline can also start from a video you already have, with an input_video node ("Your video (library)"). It has no inputs and one video output, is free and creates no job, and takes exactly one of video_job_id (a ready video job in the workspace) or video_url (the workspace's own /media URL). With this package you can also give a local .mp4 or .mov, as video_path or as a video_url that is a file path: it is checked and uploaded the same way. Wire its video into add_captions, add_voiceover, strip_audio, lip_sync or extend_video. The "Re-caption a video (your video -> captions)" template is this pair: input_video then add_captions. adsoptimiser_list_pipelines marks templates that start from your video; run them with adsoptimiser_run_pipeline and video_job_id, video_url or a local video_path, for example template_id: "video-recaption". To caption a single finished video, adsoptimiser_add_overlays is simpler. On an older deployment the pipeline tools say it doesn't support the input_video node yet.

Validating and saving use no allowance. Running does: each generation step uses allowance like a single job. Pipeline building needs an Ads Optimiser deployment that allows it for API tokens; on an older one these tools say so and templates and saved pipelines still run.

Characters and voices

A character is a saved person (an AI influencer, a brand ambassador) that keeps the same face across images and videos. A typical influencer workflow:

1. Generate a character sheet. Ask for the same person from several angles, a full-body shot and a close-up, on a neutral white background with realistic, unretouched skin.
2. Save the best shots as a character with adsoptimiser_create_character: finished jobs (job_ids), URLs, or your own photos (image_paths, checked and uploaded for you), 5 images at most. Add a description (age, face, hair, build, persona) and a voice.
3. Preview the voice. adsoptimiser_list_voices lists the xAI presets and the OpenAI voices; adsoptimiser_preview_voice plays a short sample, and with save_to saves the mp3 so you can listen locally. OpenAI voices take instructions such as accent, pacing and tone.
4. Make content. Pass character_id to adsoptimiser_generate_image for new scenes (porch, kitchen, garden), to adsoptimiser_generate_video with a script for a 9:16 talking-to-camera clip, or to a pipeline. For captioned b-roll, animate a scene image and add text with adsoptimiser_add_overlays or an add_captions step in a pipeline.

Talking clips in a designed voice now work through lip-sync. There are two ways:

• One go: run the "Character talking clip (designed voice)" template (character-lip-sync) with adsoptimiser_run_pipeline, a character_id, and the exact line as the prompt (about 20 words). It places the character in a fitting scene, animates an 8 second 720p clip, lip-syncs your line in the character's own voice (OpenAI or xAI) and adds captions. That is about US$0.72 per run in provider costs.
• Step by step: make a 2 to 10 second clip at 720p or 1080p (not 480p) with adsoptimiser_generate_video, then call adsoptimiser_lip_sync with its job id (or a URL, or a local .mp4 or .mov up to 100 MB as video_path) and the script. The line must fit the clip: speech runs about 15 characters a second, so about 20 words for an 8 second clip. The voice is voice, else the character's voice, else eve.

Each lip-sync uses one video generation from the plan allowance and counts toward the daily video quota. It takes 2 to 5 minutes; follow it with adsoptimiser_get_job.

Everything made with a character is gathered on its page in the app's Characters section: images, videos, talking clips, lip-syncs, voiceovers and captioned clips, the lines it has spoken and its voice previews. From Claude, adsoptimiser_get_character gives the counts per kind, the latest items and the latest voice previews, and adsoptimiser_list_character_assets lists the whole gallery, filtered by type and paged with cursor. Ask for "save everything Amos has made to my Desktop" and Claude passes download_to: the finished images and videos, and the speech mp3 kept with each lip-sync and voiceover, are saved to that folder, up to 20 files per call, without replacing existing files. Pass character_id to adsoptimiser_preview_voice to keep a preview in that character's history; to save a preview locally, preview the same voice and text again with save_to (a repeat is served from cache). On an older Ads Optimiser deployment without the Characters hub, adsoptimiser_get_character still returns the character and adsoptimiser_list_character_assets says the hub is not available.

adsoptimiser_generate_video with a script still speaks only xAI preset voices: a character with an OpenAI voice uses its xai_voice_id (else eve) there, and the job's Voice: note says so. OpenAI voices also narrate: an add_voiceover step speaks over a finished video in the character's voice. Characters are edited with adsoptimiser_update_character and deleted only in the app. Saving characters and previewing voices use no allowance.

Overlays and captions

adsoptimiser_add_overlays burns text into any finished video (a video job, an https URL, or a local .mp4 or .mov as video_path, uploaded for you). It works on a video you already have: there is no need to regenerate it or run a pipeline to caption or re-caption it. There are two kinds of text, and one request can use both:

• Timed cards and captions (cues). Each cue is { text, start, end, position?, style?, y?, size?, max_width? }: up to 200 characters shown from start to end seconds, at the top, center or bottom, as a caption line or a bold card. Up to 50 cues. Use these for points timed to spoken moments, for example a grade card for each subject as the presenter names it.
• Auto captions (auto_captions: true). The server transcribes the speech and captions every word as it is said, in short chunks (captions_position, default bottom). If you know the script, pass it as script: it corrects the transcript's spellings of names, brands and numbers.

Placing the text. Three optional fields fine-tune where a cue sits and how big it is:

• y, from 0.05 to 0.95: the vertical centre of the text as a fraction of the frame height (0 is the top). It overrides position.
• size: small, medium or large (default medium for a caption, large for a card).
• max_width, from 0.4 to 1.0: the width of the text block as a fraction of the frame width.

A cue's text may also hold line breaks (\n), at most 3 lines. For auto captions, captions_y (0.05 to 0.95, overriding captions_position) and captions_size (small, medium or large) do the same.

In a 9:16 talking clip the face is usually in the upper third, so keep cards below it. A face-safe grade card, on two short lines, sitting just below the middle of the frame:

{ "text": "Maths\nA+", "start": 2, "end": 4.5, "style": "card", "y": 0.62, "size": "large", "max_width": 0.7 }

position: "center" is a simpler face-safe choice when you don't need the exact height.

The request is checked on your machine first (one source, at least one cue or auto captions, text lengths and line counts, timings and every placement value), so a bad one fails before anything is sent or charged. Rendering counts as one creative job from the plan allowance, not a generation; transcription for auto captions costs about US$0.006 per minute of video. The tool returns a job id at once; follow it with adsoptimiser_get_job, which reports the cues, whether captions were added, the transcript's word count and the transcription cost. In a pipeline, the add_captions step takes the same cues (placement fields included, checked on your machine first) and a timing of speech for captions timed to the words. On an older Ads Optimiser deployment the tool says overlays aren't supported yet, and one that predates placement says it doesn't support cue placement, caption placement or line breaks yet.

Working with local files

• Use absolute paths. Claude Desktop starts servers in its own folder, so relative paths may not point where you expect. Paths starting with ~ expand to your home folder.
• Uploads: images must be PNG, JPEG, WebP or GIF, up to 10 MB (HEIC and TIFF need converting to JPEG or PNG first). Videos must be MP4 or MOV, up to 120 MB (100 MB for a lip-sync video_path). Files are checked on your machine before anything is sent.
• Downloads go to ./adsoptimiser-output by default (or your home folder's adsoptimiser-output when the server was started in a system folder). Files are named <job id>-<prompt words>.<ext>. An existing file is never replaced unless you ask for overwrite; a numbered name such as -2 is used instead. Folder paths containing .. are refused.
• Batches stop at the first plan limit, daily quota or rate limit and report which jobs were queued and the offset to resume from once you are ready. The API allows about 8 generation requests a minute per person, so a full batch of 10 may need a second call.

Configuration

| Env var | Default | Purpose | | --- | --- | --- | | ADSOPTIMISER_URL | https://api.adsoptimiser.com.au | The Ads Optimiser API to talk to | | ADSOPTIMISER_APP_URL | https://app.adsoptimiser.com.au | The web app used in links (Billing, job pages) | | ADSOPTIMISER_OUTPUT_DIR | ./adsoptimiser-output | Default folder for adsoptimiser_download_job |

Set them in the MCP config entry, for example to target another deployment or choose where downloads land:

"adsoptimiser": {
  "command": "npx",
  "args": ["-y", "@cintelisai/adsoptimiser-mcp@latest"],
  "env": {
    "ADSOPTIMISER_URL": "https://your-deployment.example.com",
    "ADSOPTIMISER_OUTPUT_DIR": "/Users/you/Documents/Ad creatives"
  }
}

Hosted connector or this package?

Ads Optimiser also has a hosted connector at https://mcp.adsoptimiser.com.au/mcp. Add it in claude.ai under Settings > Connectors > Add custom connector, and it works in Claude on the web, mobile and desktop with nothing to install. It has the same generate tools, but it runs in the cloud, so it cannot read or write files on your computer.

Use this package when you want Claude to work with local files: upload product shots from a folder, turn a folder of images into videos, run a list of prompts from a file, or save finished creatives to disk. You can use both; they are separate connections, each with its own token.

Security notes

• The token is cached in one file per host in your home folder (~/.adsoptimiser-mcp-<host>.json, mode 0600). On Windows the mode is not enforced; the file inherits your user profile's permissions, which by default only you and administrators can read. The token never appears in any config file, log or chat, and tools never return it.
• The token is generate-only: it can generate and view creatives, pipelines and characters in the one workspace you chose, save characters, preview voices and upload source media. The API refuses it for publishing, scheduling, ads and campaigns, deleting, billing, workspace settings and admin.
• Tokens are per machine and individually revocable: each appears in the app under Profile > API tokens, where you can revoke it. adsoptimiser_disconnect revokes it on the server and deletes the local copy. If a token is revoked elsewhere, the next tool call deletes the local copy and asks you to reconnect; if you lose access to the workspace, the tools tell you to reconnect to another one.
• Uploaded files are stored by Ads Optimiser under unguessable URLs so the generation models can read them. Do not upload anything you would not put in an ad.
• Media downloads fetch the public media URL directly; the token is not sent with them.
• Previews and adsoptimiser_view_image images are fetched from the Ads Optimiser API (/api/v1/media/thumbnail) with the token, like every other API call. Nothing is fetched from another host, and the token is only ever sent to the API host.

Releasing

Publishing is automated by .github/workflows/publish.yml, which runs the tests and publishes to npm with provenance when a version tag is pushed.

1. Add the release to CHANGELOG.md, then bump the version: npm version patch (or minor / major), which updates package.json and creates a vX.Y.Z commit and tag. Or edit package.json, commit, and run git tag vX.Y.Z.
2. Push the commit and the tag: git push && git push origin vX.Y.Z.

The workflow fails if the tag does not match package.json, and skips publishing (with a notice) if that version is already on npm, so re-running a tag is safe. It needs an NPM_TOKEN repository secret: a granular npm automation token with publish rights on the @cintelisai scope.

Development

npm install
npm test

The published bin is dist/server.mjs, a single ES module bundled by esbuild (npm run build, scripts/build.mjs) with the MCP SDK and zod inside it, so the package has no runtime dependencies. npm test builds it first; npm pack and npm publish rebuild it. The licences of the bundled packages ship in dist/THIRD-PARTY-NOTICES.txt.

• npm start runs the unbundled source (server.mjs); npm run start:dist runs the bundle.
• npm run smoke starts the bundle over stdio and times initialize and tools/list.

Tests use node --test against a local stub of the API; they need no network access or account. The bundle tests copy dist/server.mjs into an empty folder and drive it over stdio, to prove it runs with no node_modules.

Licence

MIT © Cintelis Pty Limited