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 Desktop / claude.ai (OAuth)

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

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.

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:

{
  "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

Translation content

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: 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.

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