Tool Reference

Point your AI agent at this page to quickly learn all MCP capabilities. ButterKit exposes 44 MCP tools across 5 groups. Every tool that operates on a document requires a documentId, which you obtain from document_list.

Read-only tools (the list, get, and snapshot tools, design_export_preview, and the App Store Connect check and list tools) are marked as read-only, so MCP clients that support it can run them without asking for approval each time.

Document Tools

Manage open documents.

Tool	Description
`document_list`	List all open documents. Returns each document’s ID, file path, artboard count, and base language.
`document_open`	Open a `.butterkit` file from disk.
`document_create`	Create a new blank document.
`document_snapshot`	Get a summary of a document’s state: artboard counts, languages, metadata languages.
`document_save`	Save a document to disk.
`document_close`	Close a document.

Parameters

document_open requires path (absolute path to .butterkit file).
document_snapshot, document_save, document_close require documentId.

Design Tools

Create and modify artboards, text, devices, and backgrounds.

Read

Tool	Description
`design_list_artboards`	List all artboards with IDs, names, sizes, and variant info.
`design_get_artboard`	Get full artboard detail: text blocks, image blocks, devices, background, camera.
`design_list_templates`	List available design templates. Optionally filter by `sizePresetId`.
`design_list_size_presets`	List artboard size presets (iPhone, iPad, Mac, etc.). Each preset includes its `assetPurpose`: `screenshot`, `header`, `searchResults`, or `universal`.
`design_list_device_assets`	List valid `assetName` values for `design_upsert_device`, with display names.

Artboard CRUD

Tool	Description
`design_create_artboard`	Create a new artboard. Provide `name` and either `sizePresetId` or `widthPx`/`heightPx`.
`design_delete_artboard`	Delete an artboard and all its language variants. Requires `artboardId`.
`design_apply_template`	Apply a design template to an artboard (sets devices, background, text styles). Requires `artboardId` and `templateId`.

Background

Tool	Description
`design_set_background`	Set artboard background. `type` is `"color"`, `"gradient"`, or `"image"`. Provide `colorHex` for solid, `topHex`/`bottomHex` for gradient, or `imagePath` for image.

`set_background` Image Parameters

Parameter	Description
`imagePath`	Absolute path to a PNG, JPEG, or HEIC file. The image is copied into the document. Must be within the user’s configured Agent Import Folder or the MCPAssets staging directory.
`fill`	`"fit"`, `"fill"` (default), or `"stretch"`. Can be sent without `imagePath` to change the fill of an existing image background.

Text Blocks

Tool	Description
`design_upsert_text_block`	Create or update a text block. Omit `textBlockId` to create new.
`design_remove_text_block`	Remove a text block by `textBlockId`.

`upsert_text_block` Parameters

Parameter	Description
`string`	The text content.
`fontFamily`	Font family name.
`weight`	One of: `ultralight`, `thin`, `light`, `regular`, `medium`, `semibold`, `bold`, `heavy`, `black`.
`sizePt`	Font size in points.
`colorHex`	Text color as hex string.
`alignment`	One of: `leading`, `center`, `trailing`.
`paddingTop`	Top padding as a percentage (0 to 100).
`paddingSides`	Side padding as a percentage (0 to 40).
`role`	Text block role.

Image Blocks

Tool	Description
`design_upsert_image_block`	Create or update an overlay image on an artboard. Omit `imageBlockId` to create new. Supports image file import, role, scale, position, opacity, rotation, and ordering.
`design_remove_image_block`	Remove an overlay image from an artboard.

`upsert_image_block` Parameters

Parameter	Description
`imageBlockId`	UUID of existing image block to update (omit to create new).
`imagePath`	Absolute path to the image file. Required when creating a new image block. Must be within the user’s configured Agent Import Folder or the MCPAssets staging directory.
`role`	Role/name shown in the Images inspector.
`xPct`	Horizontal position percentage (-100 to 200, default 50).
`yPct`	Vertical position percentage (-100 to 200, default 50).
`scalePct`	Image scale percentage (0.1 to 200, default 30).
`opacity`	Image opacity percentage (0 to 100, default 100).
`rotationDeg`	Clockwise rotation in degrees about the image center (0 to 360, default 0).
`index`	0-based order position within the artboard’s image list.

3D Device Models

Tool	Description
`design_upsert_device`	Add or update a 3D device model. Omit `modelId` to add new.
`design_set_device_screenshot`	Set or clear the screenshot on a device’s screen. Requires `modelId`. Provide `screenshotPath` to import an image, or set `clear` to `true` to remove it.
`design_remove_device`	Remove a device model by `modelId`.

`upsert_device` Parameters

Parameter	Description
`assetName`	Device asset name (e.g. `"iPhone18ProMax"`, `"iPhoneDuo"`, `"iPadPro129"`). Use `design_list_device_assets` for all valid values.
`deviceStyle`	One of: `"realistic"`, `"clay"`, `"uiOnly"`.
`realisticFinish`	iPhone 18 Pro Max finish: `iphone18pro.burgundy.v1`, `iphone18pro.glacier.v1`, `iphone18pro.silver.v1`, `iphone18pro.black.v1`, or `original`. Preserved when switching to Clay or UI Only.
`clayColorHex`	Clay color as hex (only applies when `deviceStyle` is `"clay"`).
`hingeAngleDeg`	iPhone Duo hinge angle from `0` (closed) to `180` (flat).
`showsDisplayCutout`	Show the camera cutout on supported devices (iPhone 18 Pro Max display or iPhone Duo cover screen). Defaults to `true`. UI Only hides it while preserving this preference.
`rotationDeg`	Rotation as `[x, y, z]` in degrees.
`scale`	Device scale factor.
`positionOffset`	Position offset as `[x, y, z]`.

`set_device_screenshot` Parameters

Parameter	Description
`modelId`	UUID of the device model (from `design_get_artboard`).
`screenshotPath`	Absolute path to the screenshot image. Must be within the user’s configured Agent Import Folder or the MCPAssets staging directory.
`screenRole`	`"primary"` (default) or `"cover"`. On iPhone Duo, `primary` spans both inner halves and `cover` targets the outer cover screen.
`clear`	Set to `true` to clear the screen instead of importing a file.

Screenshot Folder

Tool	Description
`design_link_screenshot_folder`	Link a folder of screenshots that auto-map to devices by locale and device type. Requires `folderPath` (absolute path to the screenshot folder).
`design_refresh_screenshots`	Re-scan the linked folder and apply images to matching devices.

Export Tools

Render artboards to images.

Tool	Description
`design_export_artboards`	Export artboards as PNG files to a directory at their native (1x) size. Requires `outputDir`. Optionally filter by `artboardIds`.
`design_export_preview`	Render a single artboard and return it as a base64-encoded PNG for visual inspection. Requires `artboardId`.

Localization Tools

Manage languages, translations, and App Store metadata.

Languages

Tool	Description
`localization_list_languages`	List existing and available languages with variant counts.
`localization_set_base_language`	Set the base (source) language code for the document.
`localization_add_language`	Add a target language. Requires `languageCode`. Creates variant artboards for all base artboards. Set `autoTranslate` (default `true`) to auto-translate text.
`localization_remove_language`	Remove a language and all its variant artboards.

Translation

Tool	Description
`localization_set_translated_text`	Manually set translated text on a variant artboard’s text block. Requires `artboardId`, `textBlockId`, `translatedString`.
`localization_translate_artboard`	Queue auto-translation of a base artboard’s text into a target language. Requires `artboardId` and `languageCode`.

App Store Metadata

Tool	Description
`localization_get_metadata`	Get App Store metadata (description, promotionalText, whatsNew) for a language. Optional `languageCode` (omit for the base language).
`localization_set_metadata`	Set metadata fields. Optional `languageCode` (omit for the base language).
`localization_list_metadata_languages`	List languages that have metadata configured.
`localization_translate_metadata`	Auto-translate base metadata into a target language.

`set_metadata` Parameters

Parameter	Limit
`description`	Max 4,000 characters
`promotionalText`	Max 170 characters
`whatsNew`	Max 4,000 characters

App Store Connect Tools

Upload screenshots, Header and Search Results artwork, and metadata to App Store Connect. Requires API credentials configured in the App Store Connect section under ButterKit > Settings > Integrations.

Tool	Description
`asc_check_credentials`	Check whether ASC API credentials are configured.
`asc_test_connection`	Test the ASC API connection.
`asc_list_apps`	List all apps accessible with the configured API key.
`asc_list_versions`	List App Store versions for an app, showing which are editable. Requires `appId`. Optional `platform`.
`asc_create_version`	Create a new App Store version. Requires `appId` and `versionString`. Optional `platform`.
`asc_upload_screenshots`	Render artboards and upload as screenshots. Requires `documentId`, `appStoreVersionId`, `locale`. Optional `platform` and `artboardIds` (array of artboard UUIDs to upload; omit for all eligible artboards for the platform).
`asc_upload_creative_asset`	Render one Header, Search Results, or shared artboard and assign it to an editable iOS version for a locale. Requires `documentId`, `appStoreVersionId`, `locale`, `artboardId`. Replaces the existing artwork for that placement; shared artwork replaces both Header and Search Results. Does not submit for review or publish.
`asc_upload_metadata`	Upload metadata for a locale. Requires `documentId`, `appStoreVersionId`, `locale`. Optional `languageCode` (ButterKit language code to source metadata from, e.g. `en`, `fr`).

Platforms

The platform parameter accepts IOS, IPADOS, MAC_OS, WATCH_OS, or VISION_OS. When omitted, it defaults to the platform configured in ButterKit’s App Store Connect settings. WATCH_OS maps to the iOS version, so Apple Watch screenshots require an editable IOS version, and uploads with WATCH_OS skip artboards that aren’t Apple Watch sizes.

Header and Search Results Artwork

An artboard’s purpose comes from its size preset. Create Header, Search Results, or shared artwork by passing a preset whose assetPurpose is header, searchResults, or universal (see design_list_size_presets) to design_create_artboard. Upload it with asc_upload_creative_asset; asc_upload_screenshots handles regular screenshots only. The artboard must have artwork for the requested locale’s language.

ID Reference

All IDs are obtained from the corresponding list tools:

ID	Obtained from
`documentId`	`document_list` or `document_open`
`artboardId`	`design_list_artboards`
`templateId`	`design_list_templates`
`sizePresetId`	`design_list_size_presets`
`textBlockId`	`design_get_artboard`
`imageBlockId`	`design_get_artboard`
`modelId`	`design_get_artboard`
`assetName`	`design_list_device_assets`
`appId`	`asc_list_apps`
`appStoreVersionId`	`asc_list_versions`

Language Codes

Translation: ISO 639-1 codes (e.g. "en", "es", "fr", "ja", "de").
App Store Connect: Apple locale format (e.g. "en-US", "fr-FR", "ja").

Quick Help

Need more help? Browse the Documentation
Check out our Templates & Add-ons
Join us on Discord for quick help
Any other questions? Get in touch

Set Up with OpenAI Codex Workflows