Blocks Translation MCP

An MCP server that finds new UI translation keys in your codebase, dedup-checks them against a Blocks/UILM tenant, and generates the JSON the Blocks portal expects for import — for any project, framework, or language set, driven by a single per-project config file.

It never guesses tenant IDs, module names, or supported languages — those are resolved live from your config and the tenant itself. Translation text is inferred/authored by the agent; this server does the deterministic parts (diff scanning, dedupe, exact JSON stamping) in code so they're fast, cheap, and reliable.

• Works in any MCP client — Claude Code, Cursor, Codex, Google Antigravity, Pi, Windsurf, Cline, VS Code, Zed, …

• Any frontend framework — built-in ngx-translate and react-i18next extractors, plus a generic regex mode for anything else.

• Zero hardcoded languages — cultures come from the tenant's own Language/Gets API and are cached per project.

• Per-project config — one .env.blocks-translation file at each consuming repo's root; no secrets ever live in this server.

Contents

• Quick start

• Tools

• Install

• Add to your AI tool — Claude Code · Cursor · Codex · Antigravity · Pi · Windsurf · Cline · VS Code · Zed · generic

• Configure your project

• How it works

• How the server finds your project

• Troubleshooting

Related MCP server: Translations MCP Server

Quick start

# 1. Build the server (once)
git clone <repo-url> blocks-translation-mcp
cd blocks-translation-mcp && npm install && npm run build

# 2. Configure a project that uses Blocks
cp .env.blocks-translation.example /path/to/your/project/.env.blocks-translation
#    …then fill in BLOCKS_TENANT_ID, BLOCKS_PORTAL_KEY, BLOCKS_USERNAME, BLOCKS_PASSWORD

# 3. Register the server in your AI tool (see "Add to your AI tool"), then just ask:
#    "sync the translation keys"

Tools

Most of the time the agent only needs prepare_sync → sync_keys; the rest are composable building blocks.

Install

Recommended: one command (auto-detects your AI tools)

npx -y github:mahmudul006/blocks-translation-mcp install

This detects the AI tools installed on your machine (Claude Code, Cursor, Codex, Antigravity, Pi, Windsurf, Cline, VS Code, Zed…), asks global vs project, and registers the server into each — using each tool's own CLI or config format. It backs up any file before editing and only ever touches its own blocks-translation entry.

Flags (all optional — omit them to be prompted):

Requires Node ≥ 18; no clone or build. Then configure your project (the .env.blocks-translation) and restart your tool.

Uninstall / re-try

npx -y github:mahmudul006/blocks-translation-mcp uninstall           # prompts for scope
npx -y github:mahmudul006/blocks-translation-mcp uninstall --scope global --yes

Removes only the blocks-translation entry from each tool (via its remove-CLI or by editing its config, backing up first), and lists any you must remove by hand. Accepts the same --scope / --root / --print flags.

Re-fetching a new version: npx github: caches the cloned repo, so after the server is updated on GitHub, clear the cache before re-running: rm -rf ~/.npm/_npx.

Manual / from source

If you'd rather not use npx github:, clone and build, then use the per-client blocks below with node /abs/path/to/dist/index.js instead of the npx command:

git clone https://github.com/mahmudul006/blocks-translation-mcp
cd blocks-translation-mcp && npm install && npm run build

Add to your AI tool

The installer above does this for you. To do it by hand, every client runs the same stdio command:

npx -y github:mahmudul006/blocks-translation-mcp

Only two things differ per client: where the config lives and its wrapper key (mcpServers JSON, VS Code's servers, Zed's context_servers, or Codex's TOML). If your client doesn't start the server with its working directory set to your project root, add "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" to the server's env (see How the server finds your project).

GUI clients + nvm: the one-command installer handles this, but if you configure a GUI client (Antigravity, Cursor, Windsurf, VS Code) by hand and Node is installed via nvm, use an absolute command (full path to npx) and add your Node bin dir to env.PATH — otherwise the tool can't find npx/node. See Troubleshooting. Command-line clients (Claude Code, Codex) don't need it.

Claude Code

claude mcp add blocks-translation -- npx -y github:mahmudul006/blocks-translation-mcp

or in .mcp.json (project) / ~/.claude.json (global):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"]
} } }

Claude Code sets the server's cwd to your project root, so .env.blocks-translation is found automatically — no BLOCKS_PROJECT_ROOT needed.

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Codex (OpenAI Codex CLI)

~/.codex/config.toml (or a project .codex/config.toml):

[mcp_servers.blocks-translation]
command = "npx"
args = ["-y", "github:mahmudul006/blocks-translation-mcp"]

[mcp_servers.blocks-translation.env]
BLOCKS_PROJECT_ROOT = "/abs/path/to/your/project"

or via CLI:

codex mcp add blocks-translation --env BLOCKS_PROJECT_ROOT=/abs/path/to/your/project -- npx -y github:mahmudul006/blocks-translation-mcp

Google Antigravity

In the IDE: Manage MCP Servers → View raw config, or edit .agents/mcp_config.json (workspace) / ~/.gemini/config/mcp_config.json (global):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Pi (pi coding agent)

.mcp.json in your project (or the pi agent directory). Pi supports a cwd field, so you can point the server at your repo directly:

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "cwd": "/abs/path/to/your/project"
} } }

Because Pi loads .mcp.json from the project cwd, a project-local config also finds .env.blocks-translation automatically.

Windsurf

~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Cline (VS Code extension)

Cline → MCP Servers → Configure (cline_mcp_settings.json):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

VS Code (Copilot agent mode)

.vscode/mcp.json — note VS Code uses servers (not mcpServers) and an explicit type:

{ "servers": { "blocks-translation": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "${workspaceFolder}" }
} } }

Zed

settings.json — Zed uses context_servers:

{ "context_servers": { "blocks-translation": {
  "source": "custom",
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Any other MCP client (generic stdio)

Any client that speaks MCP over stdio works. Register a stdio server with:

• command: npx

• args: ["-y", "github:mahmudul006/blocks-translation-mcp"]

• env (optional): BLOCKS_PROJECT_ROOT (if the client doesn't set cwd to your repo), or the full BLOCKS_* set instead of a .env file.

Configure your project

Copy the example into your project's repo root (not this server's directory) and fill it in:

cp /abs/path/to/blocks-translation-mcp/.env.blocks-translation.example \
   /abs/path/to/your/project/.env.blocks-translation

Add .env.blocks-translation (and .blocks-translation-cache.json) to your project's .gitignore — the config holds credentials.

Config is read lazily, only when a tool runs, with this precedence per key: explicit BLOCKS_* env vars (e.g. from your client's env block) win over values in .env.blocks-translation.

How it works

The lean, token-cheap flow for adding or syncing translation keys — usually two tool calls:

1. prepare_sync — one call. Scans the diff (working-tree + staged + untracked), groups keys by their own module, fetches the tenant's cultures, and exact-dedupes each module's keys. Returns { cultures, modules: [{ module, newKeys, existingSkip }] }.

2. Translate — for each module's newKeys only, the agent infers English from the key name and translates into the returned cultures. (This server does not translate for you, and does not read your local i18n files — the portal is the source of truth.)

3. sync_keys — once per module, writes blocks-translation-helper/blocks-upload.<module>.generated.json (path configurable) and reports any duplicateWarnings (same English under a different existing key) for you to decide on.

4. Manual portal import — importing the generated JSON into the Blocks portal is a step you do yourself; this server never calls a write/import endpoint.

In clients that surface MCP server instructions (e.g. Claude Code), this workflow is injected automatically. In clients that don't, just ask for a tool by name (e.g. "run prepare_sync").

Languages: on first use the server logs in, calls Language/Gets for your tenant, and caches the result to .blocks-translation-cache.json at your project root (with a module-name → id cache). Pass refresh:true to prepare_sync/list_cultures if the tenant later adds a language.

How the server finds your project

The server needs your project's root to read .env.blocks-translation, run git diff, and place the cache. It resolves it with this precedence:

1. Explicit BLOCKS_* env vars set in your client's server config (highest priority).

2. BLOCKS_PROJECT_ROOT/.env.blocks-translation if BLOCKS_PROJECT_ROOT is set.

3. <cwd>/.env.blocks-translation — the zero-config default when the client sets cwd to your project (Claude Code, project-local Pi).

So: on Claude Code (and project-local Pi) it just works; on other clients, set BLOCKS_PROJECT_ROOT (or put the BLOCKS_* vars straight in the env block).

Troubleshooting

"No Blocks config found for this project" — BLOCKS_TENANT_ID isn't set. Create .env.blocks-translation at your project root (copy the example) or set BLOCKS_PROJECT_ROOT / the BLOCKS_* vars in your client's env block.

Missing admin credentials (BLOCKS_USERNAME/BLOCKS_PASSWORD/BLOCKS_PORTAL_KEY not set) — prepare_sync, list_modules, and language lookups use the admin surface. Set all three.

406 Invalid_Origin_Or_Referer — your Blocks deployment isn't the default cloud host. Set BLOCKS_ORIGIN to your portal's origin.

exec: "npx": executable file not found in $PATH / /usr/bin/env: 'node': No such file or directory — a GUI-launched client (Antigravity, Cursor, Windsurf, VS Code) spawned the server without your shell's PATH, so node/npx aren't found. Common when Node is installed via nvm (its bin dir is only on PATH inside a shell that sourced nvm). The one-command installer fixes this automatically. If you configured the client by hand, you need both an absolute command (the host resolves it against its own stripped PATH, before env) and an env.PATH (for npx's node shebang and child node/git). Find your Node bin dir with dirname $(readlink -f $(which npx)):

"blocks-translation": {
  "command": "/home/you/.nvm/versions/node/vX.Y.Z/bin/npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "PATH": "/home/you/.nvm/versions/node/vX.Y.Z/bin:/usr/local/bin:/usr/bin:/bin" }
}

CLI-installed clients (Claude Code, Codex) don't need this — they inherit your shell PATH.

find_keys/prepare_sync git error — they run git in the project root. Ensure the project is a git repo and git is on PATH; if your client doesn't set cwd, set BLOCKS_PROJECT_ROOT.

Admin vs. public surface — the admin surface (prepare_sync language/module lookups, list_modules, list_cultures) requires the login vars. The public surface (search_keys, the dedupe fetches) needs only BLOCKS_TENANT_ID.

Cultures look stale (a newly-added tenant language is missing) — call prepare_sync/list_cultures with refresh:true, or delete .blocks-translation-cache.json.