Skip to main content
Glama
Hoyasumii

libretranslate-mcp

by Hoyasumii
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@hoyasumii/libretranslate

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

Generated by orval OpenAPI Node Windows License: MIT

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.

Related MCP server: SimpleLocalize MCP Server

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers