🌐 xcstrings-mcp

MCP server for iOS/macOS .xcstrings (String Catalog) localization. Parse, translate, validate, and export from any AI coding assistant.

Why this exists

.xcstrings files are big JSON. Loading one whole into a model burns a noticeable chunk of the context window for almost no reason — most translation work touches a handful of keys at a time. Hand-editing is also fragile: Xcode formats these files in a very specific way (the " : " spacing, key order), and a stray reformat shows up as pure diff noise on the next commit. And then there are CLDR plurals, where every locale wants its own subset of one/few/many/other — easy to miss, painful to debug.

xcstrings-mcp is a small Rust process that sits between the assistant and the file. The assistant calls structured tools (read this batch, validate that translation, write the result atomically); the bytes on disk stay byte-identical to what Xcode would produce.

Features

• 27 MCP tools, 8 prompts, and 11 CLI commands for the full translation lifecycle
• Batch translation that fits the context window: pull 50–100 keys at a time
• Format specifier and CLDR plural validation, so %d/%@ mismatches and missing plural forms get caught before they ship
• Atomic writes that match Xcode's JSON formatting exactly (" : " colon spacing, preserved key order, BOM stripped on read and never re-emitted)
• Legacy migration from .strings and .stringsdict (UTF-8/UTF-16, plural rules, positional specifiers)
• XLIFF 1.2 import/export for handing files off to external translators
• Glossary support so terminology stays consistent across locales
• Tested with Claude Code, Cursor, VS Code + Copilot, Windsurf, Zed, and OpenAI Codex; should work with any MCP client

Quick Start

Install

brew install Murzav/tap/xcstrings-mcp
# or
cargo install xcstrings-mcp
# or
cargo binstall xcstrings-mcp

Configure

claude mcp add xcstrings-mcp -- xcstrings-mcp

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "xcstrings-mcp": {
      "command": "xcstrings-mcp",
      "args": []
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "xcstrings-mcp": {
      "command": "xcstrings-mcp",
      "args": []
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "xcstrings-mcp": {
      "type": "stdio",
      "command": "xcstrings-mcp",
      "args": []
    }
  }
}

Add to Zed settings (settings.json):

{
  "context_servers": {
    "xcstrings-mcp": {
      "command": {
        "path": "xcstrings-mcp",
        "args": []
      }
    }
  }
}

Add to your project's codex.json or configure via Codex CLI:

{
  "mcpServers": {
    "xcstrings-mcp": {
      "command": "xcstrings-mcp",
      "args": []
    }
  }
}

xcstrings-mcp communicates via stdio using JSON-RPC. Point your MCP client to the binary:

command: xcstrings-mcp
transport: stdio

Usage

The basic loop:

1. Parse the .xcstrings once to cache it.
2. Pull untranslated strings in batches.
3. Submit translations. The server validates and writes atomically.

parse_xcstrings → get_untranslated → submit_translations

For projects with multiple .xcstrings files, parse each one. The server keeps them all in memory and tracks which is "active". list_files shows what's loaded.

Tools

Prompts

Migrating from legacy .strings

If you're moving from .strings / .stringsdict:

discover_files → import_strings → get_untranslated → submit_translations

Always preview with dry_run before writing:

import_strings(directory: "./Resources", source_language: "en", output_path: "./Localizable.xcstrings", dry_run: true)
import_strings(directory: "./Resources", source_language: "en", output_path: "./Localizable.xcstrings")

If your project uses .stringsdict plurals, pull plural keys explicitly after import:

import_strings → get_plurals → get_untranslated → submit_translations

Migration handles UTF-8 and UTF-16, single- and multi-variable plural rules with positional specifiers, developer comments, unquoted keys, and merging into an existing .xcstrings.

Starting from scratch

For a brand-new file:

create_xcstrings → add_keys → add_locale → get_untranslated → submit_translations

The extract_strings prompt walks the assistant through pulling hardcoded strings out of Swift source and into the catalog.

CLI Commands

Same binary, just call it with a subcommand. Useful in CI, shell scripts, or for one-off poking around without an assistant.

CLI commands auto-discover .xcstrings in the current directory tree, so most invocations don't need a path:

cd MyProject/
xcstrings-mcp coverage              # finds Localizable.xcstrings on its own
xcstrings-mcp validate --locale uk
xcstrings-mcp add-locale fr
xcstrings-mcp export --locale de -o out.xliff

--json is available everywhere for machine-readable output. Mutating commands support --dry-run.

CLI Options

xcstrings-mcp --glossary-path ./my-glossary.json

Claude Code Skill

There's a Claude Code skill shipped with the project that teaches Claude how to drive all 27 tools well. It activates automatically on localization-related requests.

What it actually does for you:

• Stops Claude from reading raw .xcstrings files (which would just dump tens of thousands of tokens into the context for no benefit)
• Picks the right tool sequence per workflow (translate, migrate, audit, export)
• Handles CLDR plural categories per locale (Ukrainian wants one/few/many, Japanese only wants other)
• Keeps glossary terms consistent across translations
• Spawns one subagent per language for parallel multi-locale work

Install:

mkdir -p ~/.claude/skills/xcstrings-mcp && curl -sL \
  https://raw.githubusercontent.com/Murzav/xcstrings-mcp/main/skills/xcstrings-mcp/SKILL.md \
  -o ~/.claude/skills/xcstrings-mcp/SKILL.md

Or clone and copy:

cp -r skills/xcstrings-mcp ~/.claude/skills/

The skill covers full translation, language management, coverage audits, legacy migration, XLIFF roundtrips, plural handling, and glossary work.

Performance

Each platform release is a ~2.1–2.4 MB .tar.gz containing a ~4.5 MB binary (stripped, LTO). The server is event-driven on stdio, so it doesn't tick when no requests are in flight.

Scaling is linear in keys × locales. A typical iOS project (2–5K keys) parses in well under 60 ms.

Architecture

┌─────────────┐    stdio/JSON-RPC   ┌──────────────────┐    File I/O    ┌───────────────────────┐
│ Claude Code │◄───────────────────►│  xcstrings-mcp   │◄──────────────►│ Localizable.xcstrings │
│ (translates)│                     │ (Rust MCP server)│                │ (JSON on disk)        │
└─────────────┘                     └──────────────────┘                └───────────────────────┘

Plain layered architecture: server → tools → service → model, with io injected through the FileStore trait.

• server — MCP routing and handler dispatch
• tools — tool implementations, grouped by area (parse/extract/keys/translate/manage/...)
• service — the actual logic (parser, extractor, merger, validator, formatter), no filesystem access
• model — serde types for the .xcstrings format, CLDR plural rules, and format specifiers
• io — FileStore trait and the real filesystem implementation with atomic writes
• cli — the standalone subcommands; prompts.rs defines the MCP prompts; error.rs is the single project-wide error enum

Related

• Model Context Protocol — open protocol for AI tool integration
• Xcode String Catalogs — Apple's localization format
• CLDR Plural Rules — Unicode plural categories used for validation

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

See CONTRIBUTING.md for development setup and guidelines.