Documentation
MCP (AI Agents)
Tool Reference

Tool Reference

ButterKit exposes 40 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.

ToolDescription
document.listList all open documents. Returns each document’s ID, file path, artboard count, and base language.
document.openOpen a .butterkit file from disk.
document.createCreate a new blank document.
document.snapshotGet a summary of a document’s state: artboard counts, languages, metadata languages.
document.saveSave a document to disk.
document.closeClose 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

ToolDescription
design.list_artboardsList all artboards with IDs, names, sizes, and variant info.
design.get_artboardGet full artboard detail: text blocks, image blocks, devices, background, camera.
design.list_templatesList available design templates. Optionally filter by sizePresetId.
design.list_size_presetsList artboard size presets (iPhone, iPad, Mac, etc.).

Artboard CRUD

ToolDescription
design.create_artboardCreate a new artboard. Provide name and either sizePresetId or widthPx/heightPx.
design.delete_artboardDelete an artboard and all its language variants. Requires artboardId.
design.apply_templateApply a design template to an artboard (sets devices, background, text styles). Requires artboardId and templateId.

Background

ToolDescription
design.set_backgroundSet artboard background. type is "color", "gradient", or "image". Provide colorHex for solid, or topHex/bottomHex for gradient.

Text Blocks

ToolDescription
design.upsert_text_blockCreate or update a text block. Omit textBlockId to create new.
design.remove_text_blockRemove a text block by textBlockId.

upsert_text_block Parameters

ParameterDescription
stringThe text content.
fontFamilyFont family name.
weightOne of: ultralight, thin, light, regular, medium, semibold, bold, heavy, black.
sizePtFont size in points.
colorHexText color as hex string.
alignmentOne of: leading, center, trailing.
paddingTopTop padding.
paddingSidesSide padding.
roleText block role.

3D Device Models

ToolDescription
design.upsert_deviceAdd or update a 3D device model. Omit modelId to add new.
design.set_device_screenshotSet the screenshot image on a device’s screen. Requires modelId and screenshotPath.
design.remove_deviceRemove a device model by modelId.

upsert_device Parameters

ParameterDescription
assetNameDevice asset (e.g. "iPhone15ProMax", "iPadPro129", "MacbookPro16").
deviceStyleOne of: "realistic", "clay", "uiOnly".
clayColorHexClay color as hex (only applies when deviceStyle is "clay").
rotationDegRotation as [x, y, z] in degrees.
scaleDevice scale factor.
positionOffsetPosition offset as [x, y, z].

Screenshot Folder

ToolDescription
design.link_screenshot_folderLink a folder of screenshots that auto-map to devices by locale and device type.
design.refresh_screenshotsRe-scan the linked folder and apply images to matching devices.

Export Tools

Render artboards to images.

ToolDescription
design.export_artboardsExport artboards as PNG files to a directory. Set multiplier for scale (e.g. 2.0 for @2x). Optionally filter by artboardIds.
design.export_previewRender a single artboard and return it as a base64-encoded PNG for visual inspection.

Localization Tools

Manage languages, translations, and App Store metadata.

Languages

ToolDescription
localization.list_languagesList existing and available languages with variant counts.
localization.set_base_languageSet the base (source) language code for the document.
localization.add_languageAdd a target language. Creates variant artboards for all base artboards. Set autoTranslate (default true) to auto-translate text.
localization.remove_languageRemove a language and all its variant artboards.

Translation

ToolDescription
localization.set_translated_textManually set translated text on a variant artboard’s text block. Requires artboardId, textBlockId, translatedString.
localization.translate_artboardQueue auto-translation of a base artboard’s text into a target language. Requires artboardId and languageCode.

App Store Metadata

ToolDescription
localization.get_metadataGet App Store metadata (description, promotionalText, whatsNew) for a language.
localization.set_metadataSet metadata fields.
localization.list_metadata_languagesList languages that have metadata configured.
localization.translate_metadataAuto-translate base metadata into a target language.

set_metadata Parameters

ParameterLimit
descriptionMax 4,000 characters
promotionalTextMax 170 characters
whatsNewMax 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.

ToolDescription
asc.check_credentialsCheck whether ASC API credentials are configured.
asc.test_connectionTest the ASC API connection.
asc.list_appsList all apps accessible with the configured API key.
asc.list_versionsList App Store versions for an app. Requires appId. Optional platform (IOS, MAC_OS, IPADOS).
asc.create_versionCreate a new App Store version. Requires appId and versionString.
asc.upload_screenshotsRender artboards and upload as screenshots. Requires documentId, appStoreVersionId, locale.
asc.upload_metadataUpload metadata for a locale. Requires documentId, appStoreVersionId, locale.

ID Reference

All IDs are obtained from the corresponding list tools:

IDObtained from
documentIddocument.list or document.open
artboardIddesign.list_artboards
templateIddesign.list_templates
sizePresetIddesign.list_size_presets
appStoreVersionIdasc.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

Set Up with OpenAI CodexWorkflows