RaiGanja/kaeris-mcp

KAERIS i18n — MCP Server

AI-native localization over the Model Context Protocol. Give Claude Desktop, Cursor, Claude Code (or any MCP client) the ability to translate your app's strings into 46 languages — placeholder-safe, format-aware, incremental, with built-in Translation QA.

Tools

Tool	What it does	Calls the API?
kaeris_scan_repo	Discover a repo's i18n setup: locale files found, base language, target languages, framework guess (i18next/next-intl/vue-i18n/Flutter/Android/iOS/gettext/generic)	No
kaeris_status	Completeness/health per target locale — missing keys, extra keys, placeholder mismatches, plus the quality detectors that gate a merge in CI: number drift, lost inline tags, broken entities/escapes, ICU/CLDR plural gaps (same verdict as kaeris check --json)	No
kaeris_list_missing_keys	The exact missing/broken keys (with source text) for one target locale, so an agent knows exactly what to fix	No
kaeris_list_languages	List all supported target languages	No
kaeris_translate	Translate inline strings → per-language results, with QA (placeholder-loss & UI-overflow flags; verify=True back-translates to check meaning)	Yes
kaeris_translate_file	Translate a file on disk (JSON/YAML/.strings/.po/ARB/XML/CSV/XLIFF/.properties/.resx/.ftl), optional incremental — reproducible via kaeris.lock	Yes
kaeris_add_language	Bootstrap a brand-new target locale by translating the whole source file into it	Yes

The first four tools are local-only (no network call, no cost) — an agent can use them freely to audit and understand a repo's i18n before deciding what (if anything) to translate.

Reproducible by design

kaeris_translate_file with incremental=True keeps a kaeris.lock next to your source file — the same lock the CLI writes, so an agent and a human sharing a repo stay in sync. It records a hash of every source string plus the settings that produced it: tone, glossary, app context, and the model. That means:

• Edit one string — only that string is re-translated; everything else stays byte-for-byte.
• Change tone, glossary or context — the whole locale is re-translated, never a mix of old and new.
• Change plan — every tier runs the same model (Gemini 2.5 Flash-Lite), so upgrading does not force a re-translation. The lock records the model regardless: the day we change it, the locale is rebuilt in full instead of quietly ending up the work of two models.

Commit kaeris.lock alongside your source file so the agent, your teammates and CI all agree on what is already done.

Install

pip install kaeris-mcp

Or run it with Docker

docker build -t kaeris-mcp .
docker run -i --rm -v "$PWD:/work" -w /work kaeris-mcp

The server speaks JSON-RPC over stdin/stdout, so there is no port to expose — -i is what keeps the conversation open. Mount your project at /work and the repo-aware tools (scan_repo, status, list_missing_keys) read it directly; pass -e KAERIS_API_KEY=… for the paid tiers.

Configure your client

Claude Desktop — add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "kaeris-i18n": {
      "command": "kaeris-mcp",
      "env": {
        "KAERIS_API_KEY": "kaerisp_optional_for_pro_team"
      }
    }
  }
}

Cursor — Settings → MCP → Add, or .cursor/mcp.json:

{ "mcpServers": { "kaeris-i18n": { "command": "kaeris-mcp" } } }

Claude Code — one command:

claude mcp add kaeris-i18n kaeris-mcp

Restart the client; the KAERIS tools appear automatically.

Auth & tiers (all optional)

Env var	Purpose
KAERIS_API_KEY	Pro/Scale key — higher limits (else the free 10k-char tier is used)
KAERIS_OPENROUTER_KEY	OpenRouter key for Lifetime/BYOK — no monthly volume cap
KAERIS_API_URL	Override the API base URL

No key is required to try it — the free anonymous tier works out of the box.

Example prompts

• "Translate the strings in locales/en.json into German, Ukrainian and Japanese."
• "Add French and Spanish translations for these buttons: Save, Cancel, Delete."
• "Only translate the new keys I added to en.json — don't redo the whole file."
• "Check this repo's i18n and tell me what's missing or broken." (scans, then reports status — no API call)
• "We don't have Ukrainian yet — add it." (bootstraps a new locale via translation)

License

MIT