Skip to main content

Getting started

@hoyasumii/libretranslate is a TypeScript SDK for the LibreTranslate HTTP API, with an MCP server and a CLI built on top of it. Use it from code, from an AI agent, or from your terminal: all three share the same client.

  • SDK: typed methods for translating texts and lists, detecting languages, translating files and sending suggestions. It is generated by orval from an OpenAPI spec written for this package, and sends your API key when the instance needs one. Start at SDK.
  • MCP server (@hoyasumii/libretranslate/mcp, bin libretranslate-mcp): stdio or Streamable HTTP on 127.0.0.1. Tools to translate texts and documents, detect languages and check the instance, plus generic tools for the raw API. Start at MCP server.
  • CLI (libretranslate): every MCP tool as a subcommand, plus libretranslate mcp to configure the server, run it in the background, start it at login and register it in Claude Code, Codex and OpenCode. Start at CLI.

This is an independent, unofficial client, MIT licensed. It talks to a LibreTranslate instance over HTTP and contains no code from the LibreTranslate project.

A LibreTranslate instance​

You need an instance to talk to:

  • Your own, with Docker: docker run -p 5000:5000 libretranslate/libretranslate serves http://localhost:5000, the URL this package uses by default. It needs no API key.
  • With this CLI, when Docker is installed: libretranslate service up --languages en,pt,es does the same and saves the URL (see libretranslate service).
  • A hosted one, such as libretranslate.com, which requires an API key.

Installation​

Requires Node.js 20 or later.

npm i -g @hoyasumii/libretranslate     # or: pnpm add -g @hoyasumii/libretranslate
libretranslate mcp config              # the instance URL and, if it issues keys, an API key; saved per user
libretranslate mcp install             # registers the server (stdio) in Claude Code / Codex / OpenCode

As a library, npm install @hoyasumii/libretranslate.

A first call​

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

const lt = createLibreTranslateClient({ baseUrl: "http://localhost:5000" });
const { translatedText, detectedLanguage } = await lt.translate({ q: "Olá, mundo!", target: "en" });
// "Hello, world!", { language: "pt", confidence: 90 }

From the terminal, once libretranslate mcp config has saved a configuration:

libretranslate translate --q "Olá, mundo!" --target en
libretranslate languages --source pt

libretranslate docs opens this site.