MCP Server

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

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.

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

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:

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

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