Let AI agents manage your translations

The Translatize MCP server gives AI agents – Claude Code, Cursor, Claude Desktop, and any other Model Context Protocol client – direct, branch-scoped access to your translations. It runs over stdio and exposes 18 tools to read and write keys, translate, and manage git-like branches.

The agent workflow

With a create-own token, an agent can take a translation change from start to finish inside the conversation – and never touch main without your say-so.

1. Step 1

   Ship a feature – on its own branch

   You build a feature with your AI agent. Before touching a single string, the agent forks a translation branch off the base with create_branch. Your main branch stays untouched the whole time.

   create_branch
2. Step 2

   Add the new keys

   The agent writes the feature's new source strings to the branch in one batched call with upsert_labels – new keys are created, existing ones updated, and the base branch never sees a half-finished change.

   upsert_labelsupsert_label
3. Step 3

   Translate the missing values

   On any plan, the agent translates them itself: get_missing_translations returns each key with an empty target value, and it writes the translations back with upsert_labels. On a Professional or Agency plan it can instead hand the work to Translatize's platform AI with auto_translate and watch the job with translation_job_status.

   get_missing_translationsauto_translatetranslation_job_status
4. Step 4

   Mark for review – and ask you

   The agent marks the touched keys with set_labels_status, then calls review_changes for a diff and a platformUrl. It stops and asks: “review here in the chat, or on Translatize?” – and waits for your approval before going any further.

   set_labels_statusreview_changes
5. Step 5

   You approve – it merges and cleans up

   Once you approve, the agent folds the branch into the base with merge_branch (checking get_merge_conflicts first when needed), then removes the working branch with delete_branch. The change lands on main only after your sign-off.

   merge_branchdelete_branch

Setup

The server ships as @translatize/mcp with the binary translatize-mcp. Point your client at npx -y @translatize/mcp and pass a token – no global install needed.

Claude Code

Register the server once; Claude Code launches it on demand with npx. Drop the -e flag if TRANSLATIZE_API_TOKEN is already exported in your shell.

claude mcp add translatize -e TRANSLATIZE_API_TOKEN=mcni_xxx -- npx -y @translatize/mcp

Cursor

Add the server to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "translatize": {
      "command": "npx",
      "args": ["-y", "@translatize/mcp"],
      "env": {
        "TRANSLATIZE_API_TOKEN": "mcni_xxx"
      }
    }
  }
}

Any MCP client (Claude Desktop, etc.)

The same mcpServers block works for any client that speaks MCP over stdio – for Claude Desktop, put it in claude_desktop_config.json. For a pinned install, run npm i -g @translatize/mcp and set "command": "translatize-mcp" with "args": [].

{
  "mcpServers": {
    "translatize": {
      "command": "npx",
      "args": ["-y", "@translatize/mcp"],
      "env": {
        "TRANSLATIZE_API_TOKEN": "mcni_xxx",
        "TRANSLATIZE_API_URL": "https://api.translatize.com/v1"
      }
    }
  }
}

How it works

Every token is bound to one project and one base branch, and carries a branch scope. Call get_project_info (or list_branches) to see the base branch, the scope, and which branches the token may write to.

Branch scope

fixed (the default) – the token can only read and write its one base branch. create-own – the token may additionally create branches (always forked from the base), read/write/export the branches it created, and compare, merge, and delete those back into the base. It can never touch branches it did not create. The label and translation tools take an optional branch argument naming any branch in that allowed set; omit it to act on the base branch, and naming a branch outside the set fails with branch_not_allowed.

Environment variables

Tool catalog

Eighteen tools in four groups. Every label and translation tool accepts an optional branch argument (default: the token's base branch). When a call fails, the tool returns the API error code and a short remedy. The same operations are available over REST – see the Integration API reference.