Babelize

MCP Server

Make apps global-ready from Claude Code, Cursor, Codex and other AI agents with @babelize/mcp. The same local engine as the CLI.

The Babelize MCP server (@babelize/mcp) lets AI coding agents make your app global-ready: Claude Code, Cursor, Codex, or any MCP client. Its four local workflow tools run the same engine as npx babelize translate on your machine and write into your working tree for review with git diff. You don't need a Babelize account: use your own LLM key, or a Babelize API key for hosted translation.

The workflow

Tool	Use it to	Writes?	Needs
babelize_analyze	See what it takes to localize the app: framework and support level, i18n setup, hardcoded strings (file:line), JSX sentences kept whole as one ICU message, strings that can't be wired and why, locale coverage, unused keys, next steps	No (dry run on a temp copy)	—
babelize_translate	Extract strings, wire them to next-intl / react-i18next, and translate into to locales	Yes, into the working tree	Key in the server env, clean git tree
babelize_check	QA of the locale files: missing or empty keys, untranslated values, lost placeholders and tags, invalid ICU, wrong plural forms, glossary violations	No	—
babelize_review	The same QA, limited to the locale entries changed in the git diff, plus stale translations of changed source strings	No	Git repo

Agents follow the loop analyze → translate → check / review → fix → repeat. React, Next.js, Django and static HTML are supported; Vue and React Native are in beta.

• Clean tree rule. babelize_translate refuses to run on uncommitted changes, so its result is its own reviewable diff. Commit or stash first. dryRun: true previews on a dirty tree, and force: true overrides.
• Incremental runs. The lockfile (.babelize/local/babelize-lock.json) means reruns translate only new or changed strings. Failed strings are retried on the next run, and earlier locales are kept unless replace: true.
• Compact responses. Each tool returns a short summary plus compact JSON. Lists are capped (limit, default 15) and paths are relative to the project.
• Safe paths. path must stay inside the workspace. The workspace is --workspace / BABELIZE_WORKSPACE, otherwise your client's MCP roots, otherwise the server's working directory if it is a project. / and your home directory are never used.
• One run per project. A second babelize_translate on the same project while one is running is refused. Different projects run in parallel.

Translation keys

Keys come from the MCP server's environment. They are never tool arguments and are never printed.

Env var	Provider
ANTHROPIC_API_KEY	Anthropic
OPENAI_API_KEY	OpenAI
GEMINI_API_KEY	Google Gemini
GROQ_API_KEY	Groq
OPENROUTER_API_KEY	OpenRouter
BABELIZE_API_KEY	Babelize-hosted (free tier included). Create a key under Settings → API Keys. --api-key or apiKey in .babelize/config.json work too

The first BYOK key found wins, then the Babelize key. The agent can choose one with provider (and model for BYOK).

Client setup

Claude Code

claude mcp add babelize -e ANTHROPIC_API_KEY=sk-ant-... -- npx -y @babelize/mcp

Or commit a project-scoped .mcp.json. ${VAR} is read from each developer's shell:

{
  "mcpServers": {
    "babelize": {
      "command": "npx",
      "args": ["-y", "@babelize/mcp"],
      "env": { "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" }
    }
  }
}

Cursor

.cursor/mcp.json, or Settings → MCP → Add new MCP server:

{
  "mcpServers": {
    "babelize": {
      "command": "npx",
      "args": ["-y", "@babelize/mcp", "--workspace", "${workspaceFolder}"],
      "env": { "OPENAI_API_KEY": "${env:OPENAI_API_KEY}" }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.babelize]
command = "npx"
args = ["-y", "@babelize/mcp"]
env = { ANTHROPIC_API_KEY = "sk-ant-..." }

Add "--workspace", "/path/to/app" to args if the tools report the wrong folder.

Claude Desktop, opencode and others

Run npx -y @babelize/mcp as a stdio server with a key env var. If the client doesn't start servers in your project folder (Claude Desktop doesn't), add --workspace /path/to/app:

{
  "mcpServers": {
    "babelize": {
      "command": "npx",
      "args": ["-y", "@babelize/mcp", "--workspace", "/path/to/app"],
      "env": { "GEMINI_API_KEY": "..." }
    }
  }
}

Example prompts

• "Make this app global-ready in German and Japanese." The agent analyzes, translates into de and ja, runs the check, and reports the changes and any follow-ups (such as installing next-intl). The make-global-ready MCP prompt contains the same instructions.
• "What would it take to localize this app? Don't change anything." The agent runs babelize_analyze only.
• "Show me the diff for adding French, but don't write it." The agent runs babelize_translate with dryRun: true. This still calls the translator.
• "I edited the Spanish strings. Is anything broken?" The agent runs babelize_review on the uncommitted changes.
• "Review the translations in this branch against main." The agent runs babelize_review with base: "main".

Project config and glossary

The local tools read .babelize/config.json in the project for sourceLocale and an optional glossary, which babelize_check and babelize_review enforce:

{
  "sourceLocale": "en",
  "glossary": {
    "neverTranslate": ["Babelize"],
    "alwaysTranslateAs": [{ "term": "workspace", "translations": { "de": "Arbeitsbereich" } }]
  }
}

Cloud project management tools

The server also includes 30 tools for projects on babelize.co. All but the two scan tools need a Babelize API key:

export BABELIZE_API_KEY=bblz_sk_...

Or put the key in .babelize/config.json:

{ "apiKey": "bblz_sk_..." }

Common cloud tools

Tool	Parameters	Description	Auth
babelize_scan	directory (required), extensions (optional)	Scan a local directory for hardcoded strings	No
babelize_scan_strings	code (required), language (optional)	Extract translatable strings from a code snippet	No
babelize_run	project_id (required), target_locales (required), source_locale (optional), framework (optional)	Trigger a translation run	Yes
babelize_run_and_wait	project_id (required), target_locales (required), source_locale, framework, poll_interval, max_polls (optional)	Start a run and wait for it to finish	Yes
babelize_status	babel_id (required)	Check status of a translation run	Yes
babelize_glossary_get	project_id (required), search, page, limit (optional)	List glossary entries with their ids (for babelize_glossary_delete) and the total count; 100 per page by default	Yes
babelize_glossary_set	project_id (required), source (required), type (never_translate default, or always_translate_as), target and locale (required for always_translate_as)	Add or update an entry: an existing term (matched ignoring case) is updated, and always_translate_as adds or replaces one locale's translation	Yes

Full tool list: @babelize/mcp README.

No-auth scan tools

babelize_scan and babelize_scan_strings are low-level helpers that work without an API key. For a whole project, prefer babelize_analyze.

Prompts

The server exposes three MCP prompts:

Prompt	Arguments	Description
make-global-ready	locales, path (optional)	Local analyze → translate → check loop
translate-project	project_id, target_locale, source_locale (optional)	Guided flow to translate a project
scan-and-translate	directory, target_locale	Scan a local directory, then translate what was found

Resources

When an API key is configured, the server also registers two MCP resources:

• babelize://languages — supported language list
• babelize://me — the current user profile

Without an API key the resources are not registered (the two no-auth scan tools still work).

Configuration Priority

1. CLI Arguments — --api-key, --api-url
2. Environment Variables — BABELIZE_API_KEY, BABELIZE_API_URL
3. Local Config File — .babelize/config.json

Options

CLI Option	Env Variable	Default	Description
--api-key	BABELIZE_API_KEY	—	Your Babelize API key
--api-url	BABELIZE_API_URL	https://api.babelize.co	API base URL (the client appends /api itself)
--workspace	BABELIZE_WORKSPACE	client roots, else the working directory	Folder the local tools may work in

Set the URL to the origin only — including /api yourself results in requests to /api/api.

How is this guide?

[

React Native & Expo

How Babelize translates Expo Router, classic Expo and bare React Native apps — what it extracts, where translations are bundled, how the device language is picked, and current limitations.

](https://docs.babelize.co/integrations/react-native)