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

Setup

Claude (claude.ai, Desktop, mobile, Cowork)

Locize is in Claude's connector directory:

1. Open Locize in the directory, or search for "Locize" under Customize > Connectors
2. Click Connect, and your browser opens a login/consent screen
3. Sign in with your Locize account and grant the requested permissions
4. A Personal Access Token is created automatically in your profile

To add it by URL instead, use Add custom connector with https://mcp.locize.app.

Claude Code (CLI)

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.

VS Code (GitHub Copilot)

Install Locize in VS Code: VS Code opens and asks to install the server, then asks you to sign in to Locize (OAuth) when it first starts it. Or add it by hand in .vscode/mcp.json:

{
  "servers": {
    "locize": { "type": "http", "url": "https://mcp.locize.app" }
  }
}

Other HTTP-native clients (Cursor, 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:

{
  "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 28 tools organized by workflow:

Discovery

Translation content

Review

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.

Release workflow

Branch workflow

Project structure

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.

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 (role user or publisher): the structural tools (add_language, remove_language, change_languages, add_version, delete_version, copy_version, copy_language, create_branch, merge_branch, rename_namespace, delete_namespace) are blocked, and so is deleting keys with update_translations. Publishing with publish_version stays open to a translate-only publisher, as in the dashboard.
• Structural changes: add_language, remove_language, change_languages, add_version, delete_version, rename_namespace, delete_namespace and copying into a new version need the admin or manager role without a version, language or namespace restriction, exactly like the dashboard. merge_branch needs the admin or manager role; publish_version, copy_version and copy_language are open to publishers as well, inside their restriction.
• 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.

Troubleshooting

• The connector does not connect, or the sign-in page does not finish: sign in with the Locize account you use in the dashboard (email and password, or your company's SSO), confirm the second factor if your account has one, and grant the requested permissions. No Locize account yet? Create one first, then connect again.
• A tool answers with a scope error: the access was granted with fewer PAT scopes than the tool needs. Remove the connector's token in your profile under Personal Access Tokens and connect again, granting the scope.
• A tool refuses a project, language or version: your role or restriction on that project does not allow it (see Beyond PAT scopes). Call list_projects to see which projects and roles you have.
• Large namespaces: get_translations, get_published_translations and find_missing_translations answer in pages; the assistant continues with the nextPage token it gets back.
• A write stops at a plan limit: the project reached its plan's word or namespace limit, so the rest was not saved. An organization admin changes the plan in the dashboard (the tool's answer links the page); the assistant should not retry.
• Something changed in your project: every write runs as you and shows in the project's history like a change made in the dashboard.
• Revoke access: delete the token in your profile under Personal Access Tokens; the connector stops working at once.

Still stuck? Write to support@locize.com with the tool name and the time of the failure.

Data and privacy

The MCP server reads and writes your Locize project with your own permissions, nothing more. Per tool call it logs the tool name, your user id, the project id and a masked token, for operations and support; it does not store your prompts or the conversation. What a write tool sends (for example new translation texts) is stored in your project as any change from the dashboard. See the privacy policy.

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.

See also

• Why not just use AI to translate?: how Locize and AI tools complement each other
• Automatic Translation: combine saveMissing with AI auto-translation for a fully automated workflow
• Personal Access Tokens: create and manage tokens for MCP authentication