Tool Reference
Point your AI agent at this page to quickly learn all MCP capabilities. ButterKit exposes 42 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_openrequirespath(absolute path to.butterkitfile).document_snapshot,document_save,document_closerequiredocumentId.
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, 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 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. 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. 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. 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 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, default IOS). |
asc_create_version | Create a new App Store version. Requires appId and versionString. Optional platform (IOS, MAC_OS, IPADOS, default IOS). |
asc_upload_screenshots | Render artboards and upload as screenshots. Requires documentId, appStoreVersionId, locale. Optional platform (IOS, MAC_OS, IPADOS, default IOS) and artboardIds (array of artboard UUIDs to upload; omit for all). |
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). |
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