Tool Reference

ButterKit exposes 44 MCP tools across 5 namespaces. Every tool that operates on a document requires a documentId, which you obtain from document_list.

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

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, or `topHex`/`bottomHex` for gradient.

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.
`paddingSides`	Side padding.
`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, 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).
`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 the screenshot image on a device’s screen. Requires `modelId` and `screenshotPath`.
`design_remove_device`	Remove a device model by `modelId`.

`upsert_device` Parameters

Parameter	Description
`assetName`	Device asset (e.g. `"iPhone15ProMax"`, `"iPadPro129"`, `"MacbookPro16"`).
`deviceStyle`	One of: `"realistic"`, `"clay"`, `"uiOnly"`.
`clayColorHex`	Clay color as hex (only applies when `deviceStyle` is `"clay"`).
`rotationDeg`	Rotation as `[x, y, z]` in degrees.
`scale`	Device scale factor.
`positionOffset`	Position offset as `[x, y, z]`.

Screenshot Folder

Tool	Description
`design_link_screenshot_folder`	Link a folder of screenshots that auto-map to devices by locale and device type.
`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. Requires `outputDir`. Set `multiplier` for scale (e.g. `2.0` for @2x). Optionally filter by `artboardIds`.
`design_export_preview`	Render a single artboard and return it as a base64-encoded PNG for visual inspection.

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. 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.
`localization_set_metadata`	Set metadata fields.
`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 and metadata to App Store Connect. Requires API credentials configured in ButterKit > Settings > App Store Connect.

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. Requires `appId`. Optional `platform` (`IOS`, `MAC_OS`, `IPADOS`).
`asc_create_version`	Create a new App Store version. Requires `appId` and `versionString`.
`asc_upload_screenshots`	Render artboards and upload as screenshots. Requires `documentId`, `appStoreVersionId`, `locale`.
`asc_upload_metadata`	Upload metadata for a locale. Requires `documentId`, `appStoreVersionId`, `locale`.

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`
`imageBlockId`	`design_get_artboard`
`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