localizely-mcp

Servidor MCP para Localizely: gestiona archivos de traducción (Flutter ARB, iOS .strings, Android XML, JSON y más) desde cualquier cliente compatible con MCP (Claude Desktop, Claude Code, Cursor, etc.) mediante lenguaje natural.

Herramientas

Formatos de archivo compatibles: flutter_arb, json, android_xml, ios_strings, ios_stringsdict, java_properties, rails_yaml, angular_xlf, dotnet_resx, po, pot, csv, xlsx.

La API de Localizely no expone CRUD por cadena: las operaciones masivas se realizan mediante la subida/descarga de archivos; localizely_update_key crea internamente un pequeño archivo de una sola clave para ediciones puntuales.

Related MCP server: tolgee-mcp

Requisitos

• Python 3.10+

• Una cuenta y un proyecto en Localizely

• Una clave de API privada de Localizely — Ajustes de cuenta → Claves de API → https://app.localizely.com/settings/api-keys

• uv instalado (uvx se incluye con él) — recomendado, sin necesidad de clon local ni de entorno virtual

Este paquete no está publicado en PyPI. Se ejecuta directamente desde este repositorio público de GitHub mediante la compatibilidad con git de uv: no requiere pasos adicionales de despliegue ni publicación.

Uso

Claude Desktop / Claude Code — recomendado (uvx, sin clonar)

Añade a tu configuración de MCP (claude_desktop_config.json o .mcp.json):

{
  "mcpServers": {
    "localizely": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/adborroto/localizely-mcp", "localizely-mcp"],
      "env": {
        "LOCALIZELY_API_TOKEN": "your-api-token",
        "LOCALIZELY_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

uvx obtiene el repositorio, crea un entorno aislado y ejecuta el punto de entrada localizelzely-mcp bajo demanda; no hay que instalar ni actualizar nada manualmente. Fija un commit/tag específico para mayor estabilidad con git+https://github.com/adborroto/localizely-mcp@<tag-or-sha>.

Reinicia el cliente después de editar la configuración.

Clon local (alternativa)

git clone https://github.com/adborroto/localizely-mcp.git
cd localizely-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install .

cp .env.example .env
# edit .env and set LOCALIZELY_API_TOKEN

A continuación, apunta tu configuración de MCP directamente al Python del venv:

{
  "mcpServers": {
    "localizely": {
      "command": "/absolute/path/to/localizely-mcp/.venv/bin/localizely-mcp",
      "env": {
        "LOCALIZELY_API_TOKEN": "your-api-token",
        "LOCALIZELY_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

El servidor se comunica a través de stdio, como exige el propio protocolo MCP; no está pensado para ejecutarse de forma interactiva.

Encontrar tu ID de proyecto

Cada herramienta requiere un project_id. Encuéntralo en la página Mis proyectos de la aplicación web de Localizely: es el UUID que aparece en la URL del proyecto o en la configuración del proyecto.

Si sueles trabajar con un solo proyecto, define LOCALIZELY_PROJECT_ID en tu entorno (o en el bloque env de la configuración de MCP) en lugar de pasar project_id en cada llamada: cada herramienta recurre a esa variable cuando se omite el argumento. Puedes seguir pasando project_id explícitamente para usar otro proyecto en una llamada concreta.

Seguridad

• No hagas commit de tu archivo .env ni escribas tu token de API directamente en el código; .inimum ignore ya excluye .env.

• El token de API se lee del entorno al inicio; el servidor se niega a arrancar si no está presente.

• Trata tu clave de API de Localizely como cualquier otra credencial: limita su alcance a lo que necesites, rótala si se filtra, y no la compartas en incidencias, PRs o registros.

Si encuentras un problema de seguridad, abre un informe privado en lugar de una incidencia pública.

Licencia

MIT — ver LICENSE.