<div align="center">

# @hoyasumii/libretranslate

**Unofficial TypeScript SDK for the [LibreTranslate](https://libretranslate.com) API, with an MCP server (stdio and HTTP) and a CLI.**

[![Generated by orval](https://img.shields.io/badge/generated%20by-orval-14a394)](https://orval.dev)
[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-6ba539?logo=openapiinitiative&logoColor=white)](spec/openapi.yml)
[![Node](https://img.shields.io/badge/Node-%E2%89%A520-5fa04e?logo=nodedotjs&logoColor=white)](https://nodejs.org)
[![Windows](https://img.shields.io/badge/Windows-native%20%2B%20WSL-0078d4)](#windows)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

</div>

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

| Page                                                                         | What it covers                                                 |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Getting started](https://hoyasumii.github.io/libretranslate/docs/intro)     | an instance, installation, the first calls                     |
| [SDK](https://hoyasumii.github.io/libretranslate/docs/sdk/overview)          | the client, translation, files, errors                         |
| [MCP server](https://hoyasumii.github.io/libretranslate/docs/mcp/overview)   | transports, every tool, configuration, programmatic use        |
| [CLI](https://hoyasumii.github.io/libretranslate/docs/cli/overview)          | tools as commands, `libretranslate mcp`, Windows and WSL       |
| [API reference](https://hoyasumii.github.io/libretranslate/docs/api)         | every exported class, type and function, generated from source |
| [Contributing](https://hoyasumii.github.io/libretranslate/docs/contributing) | building, testing, the spec and the codegen, this site         |

The package has three layers, laid out like [`@hoyasumii/plane`](https://github.com/Hoyasumii/plane) and
[`@hoyasumii/signoz`](https://github.com/Hoyasumii/signoz):

1. **SDK.** Translate texts and lists, detect languages, translate documents and send suggestions. It is generated
   by [orval](https://orval.dev) 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

```sh
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

```ts
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

```sh
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

```sh
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](https://hoyasumii.github.io/libretranslate/docs/cli/windows).

## Development

```sh
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](CONTRIBUTING.md).

## License

[MIT](LICENSE) © Alan Reis Anjos