I18n Codelens MCP

i18n-codelens-mcp

Model Context Protocol (MCP) server for i18n translation files. It lets AI agents (Claude Code, Cursor, Antigravity, GitHub Copilot, Codex, Gemini CLI and any other MCP client) inspect, audit and safely edit locale JSON files without ever loading a whole locale file into the model context.

• Compact by design. Ten tools, single-line JSON results, no echoed input, limit/includeValues everywhere. A typical read costs 50-200 tokens.
• Safe by construction. No write path can reduce a locale file's key set; mixed flat/nested files are edited in place, never converted; upserts report conflicts instead of overwriting.
• Current MCP. Built on the TypeScript SDK v2: protocol revision 2026-07-28 and the 2025 revisions, server instructions, prompts (slash commands), cache hints and elicitation-based confirmation for destructive tools.
• Any layout. locales/en.json, locales/en-US.json, messages.en.json and i18next-style locales/en/common.json (namespace files, keys as common:nav.home).

This package is also the MCP backend of the i18n CodeLens VS Code extension.

Requirements

• Node.js 20 or newer
• Locale resources as JSON files
• An MCP client that supports stdio servers

Install

npx -y i18n-codelens-mcp

or

npm install -g i18n-codelens-mcp

Client setup

Every command below registers the same thing: a stdio server named i18n-codelens running npx -y i18n-codelens-mcp. Pick your client, run one line, done.

The server needs to know which project to work on. Most clients start it in the project directory, and Claude Code passes the project root explicitly, so nothing else is needed. When your client starts the server from somewhere else, add the project path with the client's env flag, for example -e WORKSPACE_ROOT=/absolute/path/to/project.

Windows PowerShell: PowerShell can swallow a bare -- before it reaches the CLI, which then reports unknown option '-y'. If that happens, quote the separator as '--', or run the command from cmd, Git Bash or WSL.

Claude Code

# for the whole team: writes .mcp.json in the repo

claude mcp add --scope project i18n-codelens -- npx -y i18n-codelens-mcp

just for you, in every project

claude mcp add --scope user i18n-codelens -- npx -y i18n-codelens-mcp

Claude Code sets CLAUDE_PROJECT_DIR for stdio servers, so the server always finds the right project. Its tool-search feature defers MCP tools; i18n_upsert_translations and i18n_get_translations are marked anthropic/alwaysLoad so the two everyday tools need no lookup. The prompts show up as /i18n-codelens:audit, /i18n-codelens:add-key and /i18n-codelens:translate-missing.

Manual configuration

Project scope is .mcp.json in the repository root:

{

"mcpServers": { "i18n-codelens": { "type": "stdio", "command": "npx", "args": ["-y", "i18n-codelens-mcp"] } } }

Google Antigravity

agy mcp add i18n-codelens -- npx -y i18n-codelens-mcp

agy mcp list, agy mcp disable i18n-codelens and agy mcp remove i18n-codelens manage it afterwards. Inside the IDE, /mcp opens the MCP manager.

Manual configuration

Global is ~/.gemini/config/mcp_config.json (Windows: %USERPROFILE%\.gemini\config\mcp_config.json), per project .agents/mcp_config.json. In the IDE: … → MCP Servers → Manage MCP Servers → View raw config.

{

"mcpServers": { "i18n-codelens": { "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "cwd": "/absolute/path/to/project", "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" } } } }

Antigravity also accepts disabled: true and disabledTools: ["i18n_format_resources"] per server.

Gemini CLI

gemini mcp add -s user i18n-codelens npx -y i18n-codelens-mcp

Use -s project to write the project's settings instead. Gemini takes the command and its arguments positionally, so no -- is needed.

OpenAI Codex CLI

codex mcp add i18n-codelens -- npx -y i18n-codelens-mcp

Manual configuration

~/.codex/config.toml:

[mcp_servers.i18n-codelens]

command = "npx" args = ["-y", "i18n-codelens-mcp"]

VS Code and Copilot Chat

code --add-mcp "{\"name\":\"i18n-codelens\",\"command\":\"npx\",\"args\":[\"-y\",\"i18n-codelens-mcp\"]}"

That writes the user profile. MCP: Add Server in the Command Palette does the same through a guided flow and can target the workspace.

Manual configuration

.vscode/mcp.json in the repository, which you can commit:

{

"servers": { "i18n-codelens": { "type": "stdio", "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": { "WORKSPACE_ROOT": "${workspaceFolder}" } } } }

OpenCode

opencode mcp add i18n-codelens -- npx -y i18n-codelens-mcp

Manual configuration

opencode.json in the project root, or ~/.config/opencode/opencode.json:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "i18n-codelens": { "type": "local", "command": ["npx", "-y", "i18n-codelens-mcp"], "enabled": true } } }

GitHub Copilot CLI

Copilot CLI adds servers from inside a session rather than from the shell. Start copilot, then:

/mcp add

Fill in the form: Server Name i18n-codelens, Server Type STDIO, Command npx -y i18n-codelens-mcp. /mcp, /mcp show i18n-codelens and /mcp delete i18n-codelens manage it afterwards.

Manual configuration

User level is ~/.copilot/mcp-config.json; for a repository commit .github/mcp.json, or drop an uncommitted .mcp.json at the project root.

{

"mcpServers": { "i18n-codelens": { "type": "local", "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": {}, "tools": ["*"] } } }

Cursor, Windsurf, Claude Desktop, Kiro, Cline and Roo Code

These clients have no command to add a server, so the configuration file is the way in. The shape is the same everywhere; only the path differs.

Cursor and Windsurf

.cursor/mcp.json in the project or ~/.cursor/mcp.json; Windsurf uses ~/.codeium/windsurf/mcp_config.json.

{

"mcpServers": { "i18n-codelens": { "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" } } } }

cursor-agent mcp list and cursor-agent mcp enable i18n-codelens manage it from the terminal once it is configured.

Claude Desktop

Open Settings → Developer → Edit Config.

{

"mcpServers": { "i18n-codelens": { "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" } } } }

Kiro

Command palette: Kiro: Open workspace MCP config (JSON) for .kiro/settings/mcp.json, or the user config at ~/.kiro/settings/mcp.json.

{

"mcpServers": { "i18n-codelens": { "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }, "disabled": false, "autoApprove": ["i18n_project_info", "i18n_get_translations", "i18n_search_keys", "i18n_file_keys", "i18n_key_references", "i18n_audit"] } } }

Zed

~/.config/zed/settings.json, or .zed/settings.json for the team. Zed calls MCP servers context_servers.

{

"context_servers": { "i18n-codelens": { "source": "custom", "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" } } } }

Cline and Roo Code

Open the extension panel → MCP Servers → Configure MCP Servers. Cline writes cline_mcp_settings.json, Roo Code mcp_settings.json or .roo/mcp.json per project.

{

"mcpServers": { "i18n-codelens": { "command": "npx", "args": ["-y", "i18n-codelens-mcp"], "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }, "disabled": false, "autoApprove": [] } } }

Sharing with a team

Commit a project-level configuration so every teammate and every agent picks up the same server without touching global settings.

Workspace root

Resolution order:

1. Per-tool workspaceDir argument (must be inside the configured root, see below)
2. CLI --workspaceRoot / --workspace-root
3. WORKSPACE_ROOT
4. CLAUDE_PROJECT_DIR (set by Claude Code)
5. Current working directory
6. Server package directory

The workspaceDir tool argument can only select a sub-directory of the configured root. A model cannot point the server at another directory on disk unless the server is started with I18N_ALLOW_ANY_WORKSPACE=1.

Configuration

Tools

| i18n_delete_keys | Yes | Remove keys; previews unless