localizely-mcp

Localizely용 MCP server입니다 — 자연어를 통해 모든 MCP 호환 클라이언트(Claude Desktop, Claude Code, Cursor 등)에서 번역 파일(Flutter ARB, iOS .strings, Android XML, JSON 등)을 관리할 수 있습니다.

Tools

지원되는 파일 형식: flutter_arb, json, android_xml, ios_strings, ios_stringsdict, java_properties, rails_yaml, angular_xlf, dotnet_resx, po, pot, csv, xlsx.

Localizely API는 문자열 단위 CRUD를 제공하지 않습니다. 대량 작업은 파일 업로드/다운로드를 통해 처리되며, localizely_update_key는 내부적으로 한 키만 포함된 작은 파일을 만들어 일회성 수정을 처리합니다.

Related MCP server: tolgee-mcp

요구 사항

• Python 3.10+

• Localizely 계정 및 프로젝트

• Localizely 비공개 API 키 — 계정 설정 → API 키 → https://app.localizely.com/settings/api-keys

• uv 설치(uvx 포함) — 권장 사항이며, 로컬 클론이나 venv가 필요하지 않습니다.

이 패키지는 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 구성에서 venv의 Python을 직접 지정하세요:

각 프로젝트 ID

모든 도구는 project_id를 사용합니다. Localizely 웹 앱의 My projects 페이지에서 찾을 수 있으며, 프로젝트 URL 또는 프로젝트 설정의 UUID입니다.

주로 단일 프로젝트를 사용한다면 매 호출에 project_id를 전달하는 대신 환경 변수(또는 MCP 구성의 env 블록)에 LOCALIZELY_PROJECT_ID를 설정하세요. 인자가 생략되면 각 도구가 이 값을 대신 사용하며, 일회성으로 다른 프로젝트를 대상으로 하려면 project_id를 명시적으로 전달할 수도 있습니다.

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

서버는 MCP 프로토콜에 예상대로 stdio를 통해 통신하며, 대화형 실행용이 아닙니다.

프로젝트 ID 찾기

모든 도구는 project_id를 받습니다. Localizely 웹 앱의 My Projects 페이지에서 찾을 수 있으며 — 프로젝트 URL 또는 프로젝트 설정에 있는 UUID입니다.

대부분 단일 프로젝트로 작업하는 경우, 매 호출마다 project_id를 전달하는 대신 환경(또는 MCP 구성의 env 블록)에 LOCALIZELY_PROJECT_ID를 설정하세요. 인자가 생략되면 각 도구는 이 값을 기본값으로 사용합니다. 일회성 호출에서 다른 프로젝트를 대상으로 하려면 project_id를 명시적으로 전달할 수도 있습니다.

보안

• .env 파일을 커밋하거나 API 토큰을 하드코딩하지 마세요. .gitignore에 이미 .env가 제외되어 있습니다.

• API 토큰은 시작 시 환경에서 읽으며, 토큰이 없으면 서버가 시작을 거부합니다.

• Localizely API 키를 다른 자격 증명과 마찬가지로 취급하세요. 필요한 범위로 한정하고, 유출되면 순환시키고, 이슈, PR, 로그에 공유하지 마세요.

보안 문제를 발견하면 공개 이슈 대신 비공개 리포터를 열어 주세요.

라이선스

MIT — LICENSE를 참조하세요.

요구 사항

• Python 3.10+

• Localizely 계정 및 프로젝트

• Localizely 비공개 API 키 — Account settings → API keys → https://app.localizely.com/settings/api-keys

• uv 설치되어 있을 것(uvx 포함) — 권장 사항이며, 로컬 클론이나 venv가 필요 없습니다.

이 패키지는 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 구성에서 venv의 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"
      }
    }
  }
}

서버는 MCP 프로토콜이 예상하는 대로 stdio로 통신합니다 — 대화형으로 실행하기 위한 용도가 아닙니다.

프로젝트 ID 찾기

모든 도구는 project_id를 사용합니다. Localizely 웹 앱의 My Projects 페이지에서 찾을 수 있습니다 — 프로젝트 URL 또는 프로젝트 설정에 있는 UUID입니다.

대부분 단일 프로젝트에서 작업한다면, project_id를 매번 전달하는 대신 환경 변수(또는 MCP 구성의 env 블록)에 LOCALIZELY_PROJECT_ID를 설정하세요. 인자를 생략하면 각 도구가 이 값을 기본값으로 사용합니다. 한 번만 다른 프로젝트를 대상으로 하고 싶다면 project_id를 명시적으로 계속 전달할 수 있습니다.

보안

• .env 파일을 커밋하거나 API 토큰을 하드코딩하지 마세요 — .gitignore에 .env는 이미 제외되어 있습니다.

• API 토큰은 시작 시 환경에서 읽어옵니다. 토큰이 없으면 서버가 시작되지 않습니다.

• Localizely API 키를 다른 자격 증명과 동일하게 취급하세요: 필요한 범위로만 사용하고, 유출되면 교체하며, 이슈나 PR, 로그에 공유하지 마세요.

보안 이슈를 발견하면 공개 이슈 대신 비공개 리포트로 알려주세요.

라이선스

MIT — LICENSE를 참조하세요.