localizely-mcp

MCP-сервер для Localizely — управление файлами переводов (Flutter ARB, iOS .strings, Android XML, JSON и другими) из любого MCP-совместимого клиента (Claude Desktop, Claude Code, Cursor и т.д.) с помощью естественного языка.

Инструменты

Поддерживаемые форматы файлов: flutter_arb, json, android_xml, ios_strings, ios_stringsdict, java_properties, rails_yaml, angular_xlf, dotnet_resx, po, pot, csv, xlsx.

API Localizely не предоставляет CRUD-операций для отдельных строк — массовые операции выполняются через загрузку/скачивание файлов; localizely_update_key под капотом создаёт крошечный файл с одним ключом для разовых правок.

Related MCP server: tolgee-mcp

Требования

• Python 3.10+

• Аккаунт и проект в Localizely

• Приватный API-ключ Localizely — Настройки аккаунта → API-ключи → https://app.localizely.com/settings/api-keys

• Установленный uv (uvx поставляется вместе с ним) — рекомендуется, локальный клон или venv не нужны

Этот пакет не опубликован в PyPI. Он запускается напрямую из этого публичного GitHub-репозитория через поддержку git в uv — отдельный деплой или публикация не требуются.

Использование

Claude Desktop / Claude Code — рекомендуется (uvx, без клонирования)

Добавьте в конфиг MCP (claude_desktop_config.json или .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 загружает репозиторий, создаёт изолированное окружение и запускает точку входа localizely-mcp по требованию — ничего устанавливать или обновлять вручную не нужно. Зафиксируйте конкретный коммит/тег для стабильности с помощью git+https://github.com/adborroto/localizely-mcp@<tag-or-sha>.

Перезапустите клиент после редактирования конфига.

Локальный клон (альтернатива)

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

Затем укажите в конфиге MCP Python из 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"
      }
    }
  }
}

Сервер работает через stdio, как того ожидает протокол MCP — он не предназначен для интерактивного запуска.

Как найти ID проекта

Каждый инструмент принимает project_id. Найдите его на странице Мои проекты в веб-приложении Localizely — это UUID в URL проекта или в настройках проекта.

Если вы в основном работаете с одним проектом, задайте LOCALIZELY_PROJECT_ID в окружении (или в блоке env конфига MCP) вместо передачи project_id при каждом вызове — каждый инструмент использует его как запасной вариант, когда аргумент опущен. Вы по-прежнему можете передать project_id явно, чтобы разово обратиться к другому проекту.

Безопасность

• Никогда не коммитьте файл .env и не хардкодьте API-токен — .gitignore уже исключает .env.

• API-токен читается из окружения при запуске; сервер отказывается запускаться без него.

• Относитесь к API-ключу Localizely как к любому другому секрету: ограничьте его необходимыми правами, ротируйте при утечке и не делитесь им в issue, PR или логах.

Если вы обнаружили проблему безопасности, пожалуйста, отправьте приватный отчёт, а не публичный issue.

Лицензия

MIT — см. LICENSE.