localizely-mcp

用于 Localizely 的 MCP 服务器 —— 可通过任何兼容 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）以自然语言管理翻译文件（Flutter ARB、iOS .strings、Android XML、JSON 等）。

工具

支持的文件格式：flutter_arb、json、android_xml、ios_strings、ios_stringsdict、java_properties、rails_yaml、angular_xlf、dotnet_resx、po、pot、csv、xlsx。

Localizely API 不提供逐条字符串的增删改接口 —— 批量操作通过文件上传/下载完成；localizely_update_key 会在底层构建一个仅含单个键的小文件，用于一次性编辑。

Related MCP server: tolgee-mcp

环境要求

• Python 3.10 或更高版本

• 一个 Localizely 账户和项目

• 一个 Localizely 私有 API 密钥 —— 账户设置 → API 密钥 → https://app.localizely.com/settings/api-keys

• 已安装 uv（uvx 随附其中）—— 推荐使用，无需本地克隆或创建虚拟环境

本包未发布到 PyPI。它通过 uv 的 git 支持直接从本 GitHub 仓库运行 —— 无需额外的部署或发布步骤。

使用方法

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：

{
  "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 Web 应用中的我的项目页面找到它 —— 即项目 URL 或项目设置中的 UUID。

如果你主要使用单个项目，可以在环境变量（或 MCP 配置的 env 块）中设置 LOCALIZELY_PROJECT_ID，这样每次调用时就不必再传 project_id —— 当该参数被省略时，每个工具都会自动回退到该值。你仍然可以显式传入 project_id 来针对不同项目进行一次性调用。

安全性

• 切勿提交你的 .env 文件或硬编码 API 令牌 —— .gitignore 已排除 .env。

• API 令牌在启动时从环境变量读取；如果缺失，服务器将拒绝启动。

• 请像对待其他任何凭据一样对待你的 Localizely API 密钥：仅授予所需的最小权限，如遇泄露请及时轮换，并且不要在 issue、PR 或日志中分享。

如果你发现安全问题，请提交私有报告，而不是公开 issue。

许可证

MIT —— 参见 LICENSE。