shiplocale-mcp

MCP server for ShipLocale — lets Claude (or any MCP client) read and edit your localized App Store / Google Play metadata: app copy, release notes, IAP display names, screenshot texts, target languages, Store Health diagnostics, and — optionally, behind an elevated scope — push approved copy to the live store listing.

How it works

ShipLocale keeps two layers, and this server mirrors that split:

Local drafts — metadata edited and AI-translated inside ShipLocale. Safe to let an agent modify freely; nothing reaches a real store.
Store push — explicit, irreversible writes to App Store Connect / Google Play. Push tools are only registered when your key (and SHIPLOCALE_SCOPES) includes the push scope, so an agent with a read translate key physically cannot ship anything.

Setup

1. Mint an API key

API keys are an Indie/Pro plan feature. In the ShipLocale dashboard: Settings → API Keys → Create. Pick a label (e.g. "MCP — Claude") and scopes:

Scope	Grants
`read`	Read apps, metadata, releases, screenshot texts, media library, target languages
`translate`	Edit local drafts, assign media to screenshot slots, trigger AI generation/translation
`health`	Read Store Health reports/overview and toggle finding suppressions
`push`	Write to the live App Store / Google Play listing — add only if you want the agent able to ship

You'll get a clientId (slk_...) and a clientSecret (sls_..., shown once).

Recommended: mint a read translate health key. Add push only when you explicitly want agentic store pushes.

2. Configure your MCP client

Requires Node.js 20+. No install step needed — npx fetches the package from npm.

Environment variables:

Variable	Required	Default	Purpose
`SHIPLOCALE_CLIENT_ID`	yes	—	API key client ID (`slk_...`)
`SHIPLOCALE_CLIENT_SECRET`	yes	—	API key secret (`sls_...`)
`SHIPLOCALE_SCOPES`	no	`read translate health`	Space-separated scopes to request — must be a subset of what the key holds
`SHIPLOCALE_API_URL`	no	`https://api.shiplocale.com`	Override for local development

Claude Code:

claude mcp add shiplocale \
  -e SHIPLOCALE_CLIENT_ID=slk_xxx \
  -e SHIPLOCALE_CLIENT_SECRET=sls_xxx \
  -- npx -y @shiplocale/shiplocale-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "shiplocale": {
      "command": "npx",
      "args": ["-y", "@shiplocale/shiplocale-mcp"],
      "env": {
        "SHIPLOCALE_CLIENT_ID": "slk_xxx",
        "SHIPLOCALE_CLIENT_SECRET": "sls_xxx"
      }
    }
  }
}

Auth is OAuth client-credentials against POST /connect/token; the server caches the 1-hour access token and re-fetches automatically on expiry or 401.

Tools

Read (`read` scope)

Tool	Description
`list_apps`	Apps in the portfolio
`list_variants`	A/B listing variants for an app
`get_app_metadata`	All draft fields × locales, with status (also IAP rows via `iapProductId`)
`list_releases` / `get_release_notes`	Releases and their What's New in every locale
`get_target_languages`	Target locales at account / app / IAP level
`get_screenshot_texts`	Screenshot headlines/captions + translations per slot
`list_media_folders`	Media-library folder tree with per-folder asset counts
`list_media`	Uploaded images in the media library — search, sort, page
`get_screenshot_slots`	Which media asset each screenshot slot holds, per device/locale
`get_character_limits`	Per-field hard character limits

Local drafts (`translate` scope — never touches the store)

Tool	Description
`update_app_copy`	Upsert base-language text for a field (incl. IAP display names)
`update_localization`	Edit any localization row; `approve: true` marks it Approved
`translate_field`	Async AI translation of a field into target locales
`improve_copy`	AI rewrite for review — returns text, saves nothing
`create_release` / `update_release_notes`	Create a release / set base What's New
`generate_release_notes`	AI-draft What's New from commit log / bullets
`translate_release_notes`	Async translation of What's New
`update_target_languages`	Set target locales (account / app / IAP level)
`update_screenshot_text` / `update_screenshot_translation`	Edit slot base text / override one translation
`translate_screenshot_texts`	Async translation of all screenshot texts
`assign_screenshot_slot` / `clear_screenshot_slot`	Put a media asset into a slot / empty it (base slot or one locale)

Store Health (`health` scope)

Tool	Description
`get_health_report`	Errors/warnings for an app, with suppression state per finding
`refresh_health`	Force an immediate re-check, bypassing the staleness TTL
`get_health_overview`	Portfolio-wide error/warning counts (Pro plan only)
`set_health_suppression` / `clear_health_suppression`	Ignore / un-ignore a finding workspace-wide

Store push (`push` scope — irreversible, live listing)

Tool	Description
`list_store_versions` / `get_store_version_localizations`	Find an editable store version and read live copy
`push_version_localization`	Write metadata to App Store Connect
`list_store_iaps` / `get_store_iap_localizations` / `push_iap_localization`	Read/write live IAP listings
`push_play_listing`	Write a Google Play listing (title/short/full description)
`push_play_release_notes`	Push What's New for one locale to a Play track
`push_screenshots`	Push all approved screenshot renders for a variant

Push tools require a connected store credential (credentialId from the dashboard's credential vault, except Play release notes, which resolve it server-side). Localizations generally must be Approved before a push picks them up.

Example prompts

"List my apps and show me which locales are missing a translated subtitle."
"Create release 2.4.0 from this commit log, generate the What's New, and translate it to all target languages."
"Shorten the German promotional text to fit the 170-char limit and approve it."
(with push) "Push the approved 2.4.0 release notes to the production track."

Development

npm install
npm run build
npm run dev        # tsc --watch
npm run typecheck

Point at a local backend with SHIPLOCALE_API_URL=https://localhost:7443 (or whatever the Aspire dashboard shows for the API).

shiplocale-mcp

shiplocale-mcp

How it works

Setup

1. Mint an API key

2. Configure your MCP client

Tools

Read (`read` scope)

Local drafts (`translate` scope — never touches the store)

Store Health (`health` scope)

Store push (`push` scope — irreversible, live listing)

Example prompts

Development

Latest Blog Posts

MCP directory API

shiplocale-mcp

How it works

Setup

1. Mint an API key

2. Configure your MCP client

Tools

Read (read scope)

Local drafts (translate scope — never touches the store)

Store Health (health scope)

Store push (push scope — irreversible, live listing)

Example prompts

Development

Latest Blog Posts

MCP directory API

Read (`read` scope)

Local drafts (`translate` scope — never touches the store)

Store Health (`health` scope)

Store push (`push` scope — irreversible, live listing)