@hoyasumii/libretranslate

Unofficial TypeScript SDK for the LibreTranslate API, with an MCP server (stdio and HTTP) and a CLI.

Documentation: hoyasumii.github.io/libretranslate (English and Português), also as llms.txt and llms-full.txt for LLMs. libretranslate docs opens it.

| Page | What it covers | | ---------------------------------------------------------------------------- | -------------------------------------------------------------- | | Getting started | an instance, installation, the first calls | | SDK | the client, translation, files, errors | | MCP server | transports, every tool, configuration, programmatic use | | CLI | tools as commands, libretranslate mcp, Windows and WSL | | API reference | every exported class, type and function, generated from source | | Contributing | building, testing, the spec and the codegen, this site |

The package has three layers, laid out like @hoyasumii/plane and @hoyasumii/signoz:

1. SDK. Translate texts and lists, detect languages, translate documents and send suggestions. It is generated by orval from an OpenAPI 3.1 spec written for this package (spec/openapi.yml), and sends the API key in the body when the instance issues keys.
2. MCP server (@hoyasumii/libretranslate/mcp, bin libretranslate-mcp). Runs over stdio or Streamable HTTP on 127.0.0.1.
   • Curated tools: libretranslate_translate, _translate_file, _detect, _languages, _status, _suggest, with orval's zod schemas as their inputs.
   • libretranslate_resources/libretranslate_describe/libretranslate_call for the raw API.
3. CLI (bin libretranslate). An MCP client: every tool becomes a subcommand. libretranslate mcp … configures, starts and stops the server, registers it with Claude Code/Codex/OpenCode and starts it at login.

[!NOTE] An independent, unofficial client, MIT licensed. It talks to a LibreTranslate instance over HTTP and contains no code from the LibreTranslate project or its MCP server, both AGPL-3.0. Not affiliated with or endorsed by the LibreTranslate project.

Installation

npm i -g @hoyasumii/libretranslate     # or: pnpm add -g, or clone + pnpm build + npm i -g .
libretranslate mcp config              # the instance URL (default http://localhost:5000) and an optional API key
libretranslate mcp install             # registers the server (stdio) with Claude Code / Codex / OpenCode

No instance yet? With Docker installed, libretranslate service up --languages en,pt,es runs one at http://localhost:5000 (no key needed) and saves it as the CLI's instance; service down|status|logs manage it. Hosted ones, such as libretranslate.com, require an API key.

SDK

import { createLibreTranslateClient } from "@hoyasumii/libretranslate";

const lt = createLibreTranslateClient({
  baseUrl: "http://localhost:5000",
  apiKey: process.env.LIBRETRANSLATE_API_KEY, // only for instances that issue keys
});

const { translatedText, detectedLanguage } = await lt.translate({ q: "Olá, mundo!", target: "en" });
const many = await lt.translateMany({ q: ["Bom dia", "Boa noite"], source: "pt", target: "es" });
const html = await lt.translate({ q: "<b>Olá</b>", source: "pt", target: "en", format: "html" });
const candidates = await lt.detect("Bonjour tout le monde");
const languages = await lt.languages();

const { translatedFileUrl } = await lt.translateFile({ file: new Blob([data]), filename: "report.docx", target: "pt" });
const translated = await lt.downloadFile(translatedFileUrl); // { data, filename, contentType }

A non-2xx answer throws LibreTranslateApiError (status, method, path, body), with the API key masked.

MCP server

libretranslate-mcp                 # stdio, what an MCP client launches
libretranslate-mcp --http          # http://127.0.0.1:3768/mcp
libretranslate mcp start           # the same, in the background; stop / status / boot enable

| Tool | What for | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------- | | libretranslate_translate | One text or a list, with auto detection, HTML and alternatives | | libretranslate_translate_file | A local document, saved beside it as <name>.<target><ext> | | libretranslate_detect | The candidate languages of a text | | libretranslate_languages | The language codes, or one source's targets | | libretranslate_status | Health, key required, character limit, file formats | | libretranslate_suggest | Sends a better translation back, when asked | | libretranslate_resources / libretranslate_describe / libretranslate_call | The raw API (writes need confirm: true) |

CLI

libretranslate translate --q "Olá, mundo!" --target en
libretranslate translate-file --path report.docx --target pt
libretranslate languages --source pt
libretranslate --url http://127.0.0.1:3768/mcp status   # through a running server

Settings resolve flag > environment (LIBRETRANSLATE_URL, LIBRETRANSLATE_API_KEY, PORT) > the saved .env (libretranslate mcp config) > defaults.

Windows

Native Windows 10/11 (PowerShell, cmd) and WSL. libretranslate mcp boot enable registers a logon task, and from WSL libretranslate mcp install also reaches the clients installed on the Windows side. See Windows and WSL.

Development

pnpm install
pnpm codegen        # spec/openapi.yml → src/generated/ (orval) + the MCP catalog
pnpm test:unit      # a fake LibreTranslate on node:http, no network
pnpm test:live      # against a real instance (.env.test, see env.example)
pnpm docs:dev       # the docs site

See CONTRIBUTING.md.

License

MIT © Alan Reis Anjos