libretranslate-mcp

An MCP server that exposes a self-hosted LibreTranslate instance as three tools: translate, detect, languages.

It is a thin, honest wrapper over LibreTranslate's REST API. It does no translation itself, has no glossary, no document translation, and no translation memory.

Deployment has not happened yet. The open items, the commands that close them, and the traps for the next session live in unraid-stack/docs/LIBRETRANSLATE-MCP-NEXT.md — in the private BaconDroid/unraid-stack repository, so the link below resolves only for account holders, not for anonymous visitors.

What is verified, and what is not

The badge above is the source of truth for the current CI state. This section deliberately makes no claim about it, because such claims go stale on every run. What follows are durable facts, none of which a CI run can change.

Verified against pinned upstream source, and exercised end to end

• The three response shapes this client parses were read directly out of LibreTranslate's own code at commit 4aca61bd (release v1.9.6), and each one matches what the client expects:

  • POST /translate returns {"translatedText": <string>}, adding detectedLanguage as {language, confidence} only when source is "auto", and alternatives — an array of plain strings — only when alternatives > 0. A second return in that route is a translation-cache hit serving the same shape, not a different one.

  • GET /languages returns [{code, name, targets}].

  • POST /detect returns an array of {language, confidence}. The upstream model2iso helper preserves that dict and only lowercases the code.

  • Two details worth knowing: upstream filters the primary translation out of its own alternatives list, so fewer candidates can come back than were requested; and a batch q (an array) puts a list into translatedText. This client only ever sends a string, so it never reaches that branch.

• The HTTP transport was then executed, against a stub serving exactly those three shapes. Observed, not reasoned about:

  • GET /health → 200 with authEnabled reported truthfully; POST /mcp with no or a wrong token → 401; GET /mcp → 405; a body over MAX_BODY_BYTES → 413; an unknown path → 404.

  • The MCP handshake completes: initialize returns 200 with protocolVersion 2025-06-18, and tools/list on a second request returns all three tools with their schemas. That second request is the point: it is what a fresh server per request means in practice, and it is the defect createServer() exists to fix in the sibling repo.

  • tools/call on all three tools parses the contract correctly, including detectedLanguage appearing only for source: "auto" and the requested/returned accounting on alternatives.

  • The defensive paths fire as designed: format: "html" with alternatives > 0 is refused before any network call, a non-2xx response reports the status, the upstream body and the endpoint, and a 200 whose shape is unrecognised fails loudly with the received payload quoted rather than returning undefined.

Two limits on that evidence, both real:

• The upstream was a stub, not LibreTranslate. It reproduced the contract confirmed in the pinned source, so it validates the client's parsing and its error handling, not LibreTranslate itself. The real round trip is still unobserved. The contract is anchored to a named commit, so if upstream changes it the claim is falsifiable rather than stale by assertion.

• It first ran under Bun 1.4.2, not Node. That run was made before the server had ever been executed at all, and Bun implements node:http, node:crypto and fetch, so it was meaningful — but the shipped image is node:22-alpine, and no request had been served by Node at the time.

Both runtime gaps are now closed. Two smoke tests run on Node in CI on every push, both against dist/index.js — what the container actually executes — and both against the same stub. No new dependency: node:assert and an exit code.

• npm run test:smoke — 15 assertions on the HTTP transport: the status paths, the MCP handshake, tools/list on a second request, tools/call on all three tools, and the defensive paths.

• npm run test:smoke:stdio — 7 assertions on the stdio transport, spoken as newline-delimited JSON-RPC over stdin/stdout. It also asserts the invariant that only makes stdio safe: a populated stdout carries JSON-RPC and nothing else, while the startup banner goes to stderr. That check runs last on purpose — before any traffic an empty stdout is correct, not a fault.

The step results are visible in the workflow; the log bodies are not readable without repository admin access, so the passes are confirmed at step level rather than by quoting the lines the tests printed. Both suites were also verified to fail when an assertion is deliberately broken, which is the only reason a green run means anything.

What is still unverified: LibreTranslate itself. The upstream in all of the above is a stub reproducing the contract read from the pinned source. It validates this client's parsing, its error handling and its framing, not the real service. The contract is anchored to a named commit, so if upstream changes it the claim is falsifiable rather than stale by assertion.

Dependency surface

• package-lock.json is committed and CI installs with npm ci, so the dependency tree is pinned and reproducible. Bumping the SDK or zod is now a deliberate, reviewable change to the lockfile rather than something that happens silently on the next run.

• The pinned versions were resolved once and never re-checked against the SDK's published type definitions by hand. The McpServer / registerTool / StreamableHTTPServerTransport calls follow the SDK's documented usage; a real signature mismatch would surface as a typecheck failure, not a silent breakage.

Not verified — published image

• unraid-stack/my-libretranslate-mcp.xml still references the placeholder REPLACE_ME/libretranslate-mcp:latest. It must be replaced with a real published image before that template will start; see unraid-stack/docs/translation-mcp.md.

To reproduce the CI checks locally on a machine with Node 20+:

npm ci
npm run typecheck
npm run build

Related MCP server: deepl-i18n

Requirements

• Node.js >= 20 (native fetch, AbortSignal.timeout, timingSafeEqual from node:crypto)

• A reachable LibreTranslate instance

• A LibreTranslate instance that has the language pairs you intend to use loaded — see "Which languages are available" below

Install and build

npm install
npm run build          # tsc -p tsconfig.json

Run

# stdio (default) — for local MCP clients that spawn the server
node dist/index.js

# http — for a container
TRANSPORT=http PORT=8787 AUTH_TOKEN=$(openssl rand -hex 32) node dist/index.js

Environment variables

All logs go to stderr, always. stdout carries the stdio JSON-RPC framing and any stray write there corrupts the protocol.

HTTP endpoints

/health is unauthenticated by design: a liveness probe that fails without a token is a liveness probe nobody runs. It exposes no secrets — service name, version, transport mode, whether auth is on, the upstream URL, and the body cap.

Clients of POST /mcp must send Accept: application/json, text/event-stream, which is what the MCP Streamable HTTP transport specifies. That is why curl alone is a poor smoke test; use the MCP inspector (see ../unraid-stack/docs/translation-mcp.md).

Tools

translate

Returns translatedText, plus detectedLanguage when the upstream response carries one. With alternatives > 0, the candidates are included when the response has them; when the field is absent, the result says so explicitly instead of returning an empty list that looks like "no alternatives existed".

format: "html" with alternatives > 0 is refused before any network call: LibreTranslate does not return alternatives for HTML input, and sending it produces a confusing upstream error instead of a clear one.

detect

languages

No input. Lists what this instance can do: code, name, and targets per language. Use it to pick valid source/target values — a language absent here cannot be used.

Which languages are available

This client does not know. LibreTranslate only loads the language models the deployment asks for (LT_LOAD_ONLY on the official container). A target value that is not loaded produces an upstream 400, which is surfaced verbatim in the tool error. Call languages to see reality.

Design notes

• Defensive response parsing. /translate accepts either a bare JSON string or an object with a translatedText string. Anything else throws an Error containing the received shape (JSON-stringified, truncated to ~300 chars) and the endpoint, so a payload change is diagnosable from the log instead of surfacing as a silent undefined. The same posture applies to /detect (array or single object) and /languages (array of objects).

• Non-2xx responses always carry the status, the endpoint, and the upstream {"error": "..."} body when there is one.

• createServer() is a factory, not a singleton. Registering tools on a module-level server instance makes it impossible to build a second one in the same process, which the stateless HTTP transport needs (one transport + one server per request). See src/server.ts.

• Body cap before buffering. The Content-Length header is checked up front, and the running total is checked on every chunk; on exceed the response is 413 and the request stream is destroyed. The body is never accumulated in full and measured afterwards.

• Token comparison is constant-time. crypto.timingSafeEqual, with a length check first because that function throws on unequal buffer lengths.

Project layout

src/
  index.ts                     entry point, TRANSPORT switch, HTTP transport
                               (auth, body cap, per-request transport)
  server.ts                    createServer() factory
  constants.ts                 shared constants
  types.ts                     shared types
  services/
    libretranslate.ts          HTTP client + defensive response parsing
  tools/
    translate.ts               registerTranslateTools
    detect.ts                  registerDetectTools
    languages.ts               registerLanguagesTools
tsconfig.json
Dockerfile
entrypoint-mcp.sh
.env.example
.github/workflows/build.yml

License

MIT