@i18nexus/mcp

Official Model Context Protocol server for managing i18nexus project strings through the i18nexus API.

This package lets MCP-compatible AI coding tools add, update, search, move, and delete i18nexus source strings without editing generated translation JSON files directly. i18nexus remains the source of truth for translations, and i18nexus automatically AI translates new and updated source strings into your project's target languages.

What It Does

Use this MCP when you want an AI coding tool to manage app copy in i18nexus while working in your codebase.

Supported operations include:

• Reading project metadata, languages, namespaces, source strings, and current translation JSON
• Adding single strings, bulk strings, and plural sets
• Updating, moving, and deleting source strings
• Creating, renaming, and deleting namespaces
• Validating string keys before creating them

This MCP focuses on source-language base strings. It does not provide tools for directly editing non-base-language translations.

New to i18nexus?

i18nexus is a translation management platform for app localization, designed especially for React and Next.js apps using common i18n libraries like i18next, next-intl, and react-intl. It includes an online dashboard where technical and non-technical team members, including translators, can manage translations together. It stores your source strings, manages target languages, and automatically AI translates new and updated strings so your app's translation files stay in sync.

Start with the Getting Started guide for a quick overview of how i18nexus works and how to set up your app.

The easiest way to get started is from your app repository:

npx @i18nexus/cli init

The init command helps create an i18nexus account, create or connect an i18nexus project, import existing translation files when applicable, set up local integration for pulling translation JSON into your app, and configure this MCP for the project.

Before You Start

You need:

• An i18nexus project API key
• A personal access token for write operations
• An MCP client that can run local MCP servers, such as Claude or Codex

If you already have an i18nexus account, you can get your project API key and personal access token from the project dashboard in the i18nexus platform.

As mentioned above, you can initialize your project with npx @i18nexus/cli init, which will give you your API key and, if you choose MCP setup, create a project-scoped token for it.

Installation

No separate install step is required. The recommended configuration below runs this package with npx.

If you prefer a global install, you can run:

npm install -g @i18nexus/mcp

Configuration

Claude Code

Project-Scoped Setup (Recommended)

Recommended because i18nexus project API keys are usually tied to a single app, so each repository should point to its own i18nexus project.

Create a .mcp.json file in the app repository:

{
  "mcpServers": {
    "i18nexus": {
      "command": "npx",
      "args": ["-y", "@i18nexus/mcp"],
      "env": {
        "I18NEXUS_API_KEY": "<PROJECT_API_KEY>",
        "I18NEXUS_PERSONAL_ACCESS_TOKEN": "<PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

Claude CLI Setup

Claude CLI setup is global, so make sure the configured i18nexus project API key matches the codebase you are working on.

For global Claude Code setup, use the Claude CLI:

claude mcp add i18nexus \
  --env I18NEXUS_API_KEY=<PROJECT_API_KEY> \
  --env I18NEXUS_PERSONAL_ACCESS_TOKEN=<PERSONAL_ACCESS_TOKEN> \
  -- npx -y @i18nexus/mcp

You can also use ~/.claude.json for global Claude Code config. Use the same JSON shape shown in the project-scoped setup above. Restart Claude Code after editing config files manually.

Claude Desktop

Claude Desktop uses global config, so make sure the configured i18nexus project API key matches the codebase you are working on.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Use the same JSON shape shown in the project-scoped setup above.

Restart Claude Desktop after editing config files manually.

Codex

Project-Scoped Setup (Recommended)

Recommended because i18nexus project API keys are usually tied to a single app, so each repository should point to its own i18nexus project. Codex only loads project-scoped config for trusted projects.

Create a .codex/config.toml file in the app repository:

[mcp_servers.i18nexus]
command = "npx"
args = ["-y", "@i18nexus/mcp"]

[mcp_servers.i18nexus.env]
I18NEXUS_API_KEY = "<PROJECT_API_KEY>"
I18NEXUS_PERSONAL_ACCESS_TOKEN = "<PERSONAL_ACCESS_TOKEN>"

Disabled Tools

To hide destructive tools from Codex, use disabled_tools:

[mcp_servers.i18nexus]
command = "npx"
args = ["-y", "@i18nexus/mcp"]
disabled_tools = ["delete_string", "bulk_delete_strings", "delete_namespace"]

[mcp_servers.i18nexus.env]
I18NEXUS_API_KEY = "<PROJECT_API_KEY>"
I18NEXUS_PERSONAL_ACCESS_TOKEN = "<PERSONAL_ACCESS_TOKEN>"

Codex CLI Setup

Codex CLI setup is global, so make sure the configured i18nexus project API key matches the codebase you are working on.

For global Codex setup, use the Codex CLI:

codex mcp add i18nexus \
  --env I18NEXUS_API_KEY=<PROJECT_API_KEY> \
  --env I18NEXUS_PERSONAL_ACCESS_TOKEN=<PERSONAL_ACCESS_TOKEN> \
  -- npx -y @i18nexus/mcp

You can also use ~/.codex/config.toml for global Codex config. Use the same TOML shape shown in the project-scoped setup above. Restart Codex after editing config files manually.

Recommended Agent Instructions

For best results, add the same instructions generated by npx @i18nexus/cli init to your project instructions, such as CLAUDE.md, AGENTS.md, or another agent instruction file:

## i18nexus

i18nexus is the source of truth for translations. Do not edit local translation
JSON files directly.

For user-facing text changes, use the i18nexus MCP to add or update
source-language strings. Call `get_i18nexus_mcp_guidance` for detailed rules.
If the MCP is unavailable or lacks the required token scope, stop and tell the
user instead of editing translation files.

Before running `i18nexus pull` after MCP string changes, check package.json
for an `i18nexus listen` script. `i18nexus listen` automatically pulls
translation JSON updates when strings change, so a manual pull is usually
unnecessary while it is running. If `listen` is configured, do not pull unless
the user explicitly asks. If `listen` is not configured, ask whether they are
already running `i18nexus listen` in another shell and whether they want you to
pull automatically after changes.

Environment Variables

| Variable | Description | | --- | --- | | I18NEXUS_API_KEY | Your i18nexus project API key | | I18NEXUS_PERSONAL_ACCESS_TOKEN | Personal access token for write operations and membership-protected reads |

Personal Access Token Scopes

Most read-only tools only need the project API key. get_string, search_strings, and get_token_scope also require a personal access token to verify project membership, but they do not require a write scope. Write tools require a personal access token with the relevant scope:

• base_strings:create
• base_strings:update
• base_strings:delete
• namespaces:create
• namespaces:update
• namespaces:delete

Use get_token_scope to check which scopes your configured personal access token has for the current project.

Available Tools

• get_i18nexus_mcp_guidance
• get_project_metadata
• get_token_scope
• list_languages
• list_namespaces
• get_string
• search_strings
• get_translation_json
• validate_string_key
• add_string
• add_plural_set
• bulk_add_strings
• update_string
• move_string
• delete_string
• preview_bulk_delete_strings
• bulk_delete_strings
• add_namespace
• rename_namespace
• delete_namespace

Keeping Local Translation Files Updated

If your project uses local translation JSON files, keep them synced with the i18nexus CLI. A common setup is:

• Run i18nexus pull before builds
• Run i18nexus listen alongside your dev server

The npx @i18nexus/cli init command can help set this up for your project.

i18nexus listen pulls translations when it starts and again whenever i18nexus sends a websocket notification that project strings changed. If your app fetches translation JSON from the i18nexus API at runtime, local file syncing may not be necessary.

Development

npm install
npm run build
npm test

For local MCP testing from this repo, build first and point your MCP client at dist/index.js:

{
  "mcpServers": {
    "i18nexus": {
      "command": "node",
      "args": ["/path/to/i18nexus-mcp/dist/index.js"],
      "env": {
        "I18NEXUS_API_KEY": "<PROJECT_API_KEY>",
        "I18NEXUS_PERSONAL_ACCESS_TOKEN": "<PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

License

MIT. Use of the i18nexus service is subject to the i18nexus terms of service. This license applies only to the MCP server source code in this repository.

Support

Questions, setup issues, or feedback? Contact us at [email protected]. We are happy to help.