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, 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:

1. Local drafts — metadata edited and AI-translated inside ShipLocale. Safe to let an agent modify freely; nothing reaches a real store.
2. 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, target languages
translate	Edit local drafts, trigger AI generation/translation
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 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	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
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

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