Locize MCP Server

Locize TMS: 26 tools for translations, TM/glossary/styleguide/screenshot context, versions. OAuth.

Documentation

Locize MCP Server

The Locize MCP (Model Context Protocol) server lets AI assistants (Claude, Cursor, GitHub Copilot, and others) interact directly with your translation projects.

Server URL: https://mcp.locize.app

smart_display

YouTube Video

This video is hosted on YouTube. Accept YouTube cookies to watch it here.

Watch on YouTubeUpdate cookie preferences

Setup

Claude Desktop / claude.ai (OAuth)

Go to Settings > Connectors > Add custom connector
Enter URL: https://mcp.locize.app
Click Connect, and your browser opens a login/consent screen
Sign in with your Locize account and grant the requested permissions
A Personal Access Token is created automatically in your profile

Claude Code (CLI)

Copy

claude mcp add --transport http locize https://mcp.locize.app

Then run /mcp in a Claude Code session and complete the OAuth flow.

Note: After first-time OAuth, Claude Code may show "Authentication successful, but server reconnection failed." This is a known Claude Code issue; simply restart Claude Code and the server will connect automatically using the stored token.

Other HTTP-native clients (Cursor, VS Code, etc.)

Add the server URL https://mcp.locize.app in your client's MCP settings and complete the OAuth flow. The exact steps vary by client; consult your client's MCP documentation.

Stdio transport (PAT alternative)

For clients that support stdio but not HTTP, use mcp-remote as a bridge:

Copy

{
  "mcpServers": {
    "locize": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.locize.app"]
    }
  }
}

Authentication

The MCP server supports two authentication methods:

OAuth 2.0 (recommended): used automatically by Claude Desktop, Cursor, and other MCP clients that support it. No manual token management needed. The OAuth flow creates a Personal Access Token in your profile automatically. Access can be revoked at any time.

Personal Access Token (PAT): for CI/CD, scripts, or clients that don't support OAuth. Create one in your profile under Personal Access Tokens. Pass it as Authorization: Bearer lz_pat_.... See the PAT documentation for details on scopes and security.

Available tools

The MCP server exposes 26 tools organized by workflow:

Discovery

Tool	Description
list_projects	List all projects accessible via your token. Call this first.
get_project_stats	Translation coverage per version, language, and namespace
list_branches	List branch projects of a parent project
list_tenants	List tenant projects of a parent project

Translation content

Tool	Description
get_translations	Fetch unpublished (editor state) translations with filtering by tags, timestamps, and pagination
get_published_translations	Fetch published (CDN) translations for a namespace
find_missing_translations	Compare a target language against the reference language; returns missing and stale keys
report_missing_keys	Add new keys (never overwrites existing). Auto-batches at 1000 keys. If Automatic Translation is enabled, new keys on the reference language are translated into all target languages automatically.
update_translations	Update or delete translation keys. Set a value to null to delete.

Context

These read-only tools give an agent the same context a human translator has, so it can translate, review, and lint in your IDE.

Tool	Description
get_glossary	Fetch the project's terminology glossary (approved & forbidden terms per language). Use each term's preferred value when translating, or lint new source strings for forbidden-term drift.
get_styleguide	Fetch the project's style guide (tone, formality, target audience, usage rules) per language
search_translation_memory	Find previously translated segments similar to a source string (exact + fuzzy) to reuse prior translations
get_screenshot_context	Fetch the screenshot(s) and mapped region where a key appears, for visual disambiguation

Release workflow

Tool	Description
publish_version	Publish a version to the CDN. Returns a jobId for status tracking.
copy_version	Copy all translations from one version to another (e.g. latest → production)
copy_language	Copy a single language between versions
get_job_status	Check or wait for async operations (publish, copy, merge) to complete

Branch workflow

Tool	Description
create_branch	Create a translation branch from a version
merge_branch	Merge a branch back into its parent project

Project structure

Tool	Description
add_language	Add a language to the project
remove_language	Remove a language and all its translations
change_languages	Replace the entire language list atomically
add_version	Add a new version
delete_version	Delete a version and all its translations
rename_namespace	Rename a namespace across all languages
delete_namespace	Delete a namespace and all its translations

Example prompts

Once connected, you can ask your AI assistant things like:

"Find all missing German translations in the checkout namespace"
"Publish the latest version of my project"
"Add Japanese to all versions"
"Create a branch for the v2 feature, translate it, then merge it back"
"Show me which keys changed in English this week"
"Report these new keys from my codebase to Locize"
"What's the translation coverage for the production version?"
"Translate these new strings using the project's glossary and style guide"
"Lint this PR's new English strings for any forbidden glossary terms"
"Show me the screenshot where the checkout.title key appears"

Agent conventions

To make your AI agent use these tools by default — fetch the glossary and style guide before translating, reuse translation memory, and lint pull requests for forbidden terms — drop our ready-made convention files (CLAUDE.md, AGENTS.md, .cursorrules) into your repo. They live in the public locize/locize-agents repository.

PAT scopes

Tools require specific PAT scopes. If a tool returns a scope error, your token needs additional permissions.

Scope	Tools
read	list_projects, get_project_stats, list_branches, list_tenants, get_translations, get_published_translations, find_missing_translations, get_glossary, get_styleguide, search_translation_memory, get_screenshot_context
write	report_missing_keys, update_translations, rename_namespace, delete_namespace
manage	publish_version, copy_version, copy_language, get_job_status, create_branch, merge_branch, add_language, remove_language, change_languages, add_version, delete_version

Beyond PAT scopes

PAT scopes are only the first gate. Your project-level role and permissions still apply on top:

Project role: your role on a given project (admin / manager / publisher / user / accountant) always wins when it is stricter than the PAT scope. For example, a PAT with manage scope called by a user whose project role is readonly still cannot modify that project.
Language / version / namespace scope: if your membership is restricted to specific languages, versions, or namespaces, get_translations and find_missing_translations will reject requests outside that scope.
translateOnly users: the structural tools (add_language, remove_language, change_languages, add_version, delete_version, publish_version, copy_version, copy_language, create_branch, merge_branch, rename_namespace, delete_namespace) are blocked for users marked translate-only.
Blocked / revoked access: if your project membership is blocked or your PAT has been revoked, every tool call fails immediately with a 401.
Parent project access: for tenant and branch projects, merging translations with the parent only happens if your PAT also has access to the parent project; otherwise you see the child-only view.

Technical details

Transport: Streamable HTTP (Web Standard Request/Response)
Auth: OAuth 2.0 (Authorization Code + PKCE with Dynamic Client Registration) or PAT Bearer token
Endpoint: POST https://mcp.locize.app
OAuth metadata: GET https://mcp.locize.app/.well-known/oauth-protected-resource
Stateless: Each request creates a fresh MCP server instance. No session management required.

Locize MCP Server

Documentation