💻 Local MCP Server (Claude Code, Codex, etc)

Bluente Translate MCP Server is the official open-source MCP server for exposing Bluente translation capabilities to AI clients. It runs locally on your machine (stdio) — for a no-install alternative, see the Hosted MCP Server (Claude) guide, or the overview comparing the two.

It wraps Bluente APIs into production-ready MCP tools so teams can automate multilingual document workflows from Claude Desktop, Claude Code, Codex, Cursor, ChatGPT Work, and other MCP-compatible runtimes — AI-powered translation with original layout retention, across 120+ languages and all major file types.

Source code: github.com/bluente/bluente-translate-mcp-server (MIT license)

🛠️ MCP Tools

• bluente_get_supported_languages
• bluente_upload_file
• bluente_get_translation_status
• bluente_translate_file
• bluente_download_file
• bluente_translate_document_workflow — end-to-end workflow (upload → start → poll → download)

These six are the tools the hosted server exposes too, so a prompt written against one works against the other. Three things differ:

Tool behavior notes:

• Confirmation gate: bluente_translate_document_workflow is a two-call flow. The first call uploads the file and returns page_count, a settings object, and a confirmation card for the user; nothing starts and no credits are deducted. To actually start, call again with the returned task_id, confirmed=true, and explicit to, to_type, and bilingual values (plus bilingual_layout when bilingual is on). A confirmed call without task_id is rejected, so no first call can start a translation.
• File sources, in order of preference: file_path (a file on the machine running the server), file_to_translate (an attachment the host hands over — this is how ChatGPT passes a file you dropped into the conversation), file_url (a publicly accessible link), or file_content_base64 (last resort, refused over 2MB decoded). task_id skips the upload entirely for a file that is already uploaded.
• bluente_translate_file: from and to are required when action="start" and optional when action="cancel". This tool has no confirmation gate: it starts translation immediately.
• to_type: pdf, word, or pptx. bluente_download_file defaults to word. bluente_translate_document_workflow also accepts an array (e.g. ["word", "pdf"]) — extra formats are download-time conversions of the same finished translation and cost no extra credits.
• entry on bluente_get_translation_status: get_status (translation progress, the default) or get_page_count (the uploaded file’s page count). The workflow tool’s status_entry accepts the same values but is not used — it polls get_page_count while the upload is processing and get_status during translation.
• bluente_download_file: output_path sets where the file is written; without it the file lands in the current working directory under the name the API returns, falling back to <id>.<to_type>. include_file_content=true also returns the bytes as base64, which is refused over 2MB. When the workflow tool downloads several formats, output_path names the first and the rest are saved beside it.
• engine is pinned: the server always sends engine=3 (LLM) and ignores whatever you pass. The Translation API also offers engine=4 (LLM Pro), but it is not reachable through MCP — call the API directly if you need it.

The confirmation card is composed by the server, not by the model, and arrives as a fenced block the model is told to paste verbatim. It lists the document name and page count, the language pair, the cost in pages, the page range, the output format(s), bilingual (and the layout when bilingual is on), and the document mode. A setting nobody chose is shown as a decision to make — (ask the user) for the target language, output format, or bilingual, and a (confirm — …) line for mode and for the bilingual layout — rather than as a settled default, so a scan is never silently translated as a standard document.

🎛️ Translation settings

These are the settings on bluente_translate_document_workflow. The raw bluente_translate_file tool takes the same choices in their older numeric form — scanned 0–3 instead of mode, and bilingual as line/paragraph/none instead of on/off.

mode — how the document should be processed. Picking this correctly matters for both quality and cost:

Cost by mode: standard and both scanned modes are 1 credit per page. image is the only mode charged above that, at 5 credits per page — the confirmation card quotes the already-multiplied total, so you never do the arithmetic yourself. Running a scan as standard translates blank pages and wastes credits regardless of mode pricing. The older numeric scanned parameter is a deprecated alias for mode.

page_range — translate only part of a document, e.g. "1-3,5". Credits are charged only for the selected pages, and the backend validates the range against the document’s real page count when translation starts.

bilingual — off produces a clean translated document; on keeps the original text alongside the translation. On the workflow tool it has no default: a confirmed call that omits it is rejected, so you will always be asked. (The default belongs to the raw bluente_translate_file, where off is spelled none.) The workflow tool accepts on, off, and none (a legacy spelling of off) — and nothing else. The older line and paragraph spellings belong to the raw bluente_translate_file, where the accepted values are line, paragraph, and none — pass off there and it is rejected. When bilingual is on, set bilingual_layout: left-right (original and translation side by side) or top-down (translation stacked under the original). These are the only two layouts Bluente supports, and the workflow tool rejects a confirmed bilingual-on call that omits the layout. The numeric vertical_bilingual flag (0 left-right, 1 top-down) is a deprecated alias; bilingual_layout wins when both are given.

Glossary — the workflow tool always translates with the glossary enabled, and its glossary and custom_glossary parameters are deprecated and ignored. On the raw bluente_translate_file tool both flags are yours to set (each defaults to 0), and the backend applies the glossary only when both are 1.

Language codes — Bluente codes are en, zh (Simplified Chinese), cht (Traditional Chinese), jp, kor, fra, spa, de, and others. Common ISO codes are aliased automatically (zh-CN/zh-Hans → zh, zh-TW/zh-Hant → cht, ja → jp, ko → kor, fr → fra, es → spa), so either form works.

Under the hood the server calls the same Translation API documented on this site:

• GET /blu_translate/supported_languages
• POST /blu_translate/upload
• GET /blu_translate/check
• POST /blu_translate/translate
• GET /blu_translate/download

⚡ Quick Start

Requirements: Node.js >= 20 (check with node --version; install from nodejs.org) and a Bluente API key. This page documents v0.4.0 and later.

Getting an API key: open your Bluente dashboard and copy a key from the API keys tab (see API Key). Treat the key like a password — it authorizes translations billed to your account, so keep it out of version control and shared documents.

Option 1: Just let your coding agent do it

The fastest way to install: don’t. If you use Claude Code, Cursor, or any MCP-capable coding agent, paste this prompt and watch it handle everything — config file, key, verification — in under a minute. Replace YOUR_KEY_HERE with your API key:

Install the Bluente Translate MCP server into this client. It’s the npm package @bluente/translate-mcp-server, run via npx -y @bluente/translate-mcp-server (stdio), and it needs the environment variable BLUENTE_API_KEY set in the server config’s env block. Use YOUR_KEY_HERE as the key. After configuring, verify the installation by calling the bluente_get_supported_languages tool and show me the result. Docs: https://github.com/Bluente/bluente-translate-mcp-server

The agent finds the right config file for its client, writes the block, and proves the install works by showing you the supported-language list.

Prefer not to paste your API key into an agent conversation? Have the agent use REPLACE_ME as the key, then edit the config file by hand and restart your client.

Option 2: Install manually

Claude Desktop

1. Open Settings → Developer → Edit Config (opens claude_desktop_config.json).

2. Add this block (merge into mcpServers if it already exists), inserting your API key:

   {
     "mcpServers": {
       "bluente-translate": {
         "command": "npx",
         "args": ["-y", "@bluente/translate-mcp-server"],
         "env": {
           "BLUENTE_API_KEY": "your_api_key_here"
         }
       }
     }
   }

3. Quit and reopen Claude Desktop. The tools icon should list six bluente_* tools.

Claude Code — one command, then restart your session and verify with /mcp:

claude mcp add bluente-translate -e BLUENTE_API_KEY=your_api_key_here -- npx -y @bluente/translate-mcp-server

Codex — one command, then restart Codex:

codex mcp add bluente-translate --env BLUENTE_API_KEY=your_api_key_here -- npx -y @bluente/translate-mcp-server

Codex stores its servers as TOML in ~/.codex/config.toml, not JSON, so to write it by hand use:

[mcp_servers.bluente-translate]
command = "npx"
args = ["-y", "@bluente/translate-mcp-server"]
 
[mcp_servers.bluente-translate.env]
BLUENTE_API_KEY = "your_api_key_here"

codex mcp list will show it as enabled, but that only confirms the config was written — it does not launch the server. The smoke test below is the real check.

Cursor — Settings → MCP → Add server, or create .cursor/mcp.json in your project with the same JSON block as Claude Desktop.

ChatGPT Work — configured through a form rather than a JSON file, and it needs the absolute path to npx. See Local MCP Server (ChatGPT Work).

Smoke test (any client): ask “What languages does Bluente translation support?” — a free, read-only call. A language list back means the key and connection both work. The first run takes a few extra seconds while npx downloads the package.

Troubleshooting the API key

The server reads BLUENTE_API_KEY from its environment — you never pass it as a tool argument or store it in a file. If the server reports Missing BLUENTE_API_KEY, the key is not reaching the server process: check the env block for typos and restart your client. When testing from a terminal, prefix the server command itself (BLUENTE_API_KEY=your_api_key_here npx -y @bluente/translate-mcp-server); in a shell pipeline the assignment must sit directly before npx — placed at the start of the line it applies only to the first command in the pipe.

Environment variables

📦 Tool responses

Every tool returns a unified envelope. Success:

{
  "ok": true,
  "tool": "bluente_upload_file",
  "data": {
    "code": 0,
    "message": "success",
    "data": { "id": "task_xxx" }
  }
}

Error — the same envelope with ok: false, in a result flagged isError:

{
  "ok": false,
  "tool": "bluente_translate_file",
  "error": {
    "name": "BluenteApiError",
    "message": "Bluente API request failed.",
    "details": { "status": 401 }
  }
}

The unconfirmed workflow call adds one thing to this: its confirmation card is emitted as a plain-text content item before the JSON envelope (and repeated inside it as data.render_to_user), so the card reaches the user verbatim in clients that only surface plain text.

⚙️ Operational notes

• A confirmed workflow call returns as soon as translation starts. Poll bluente_get_translation_status until data.status is READY, then call bluente_download_file once per format.
• auto_download=true instead blocks until the translation finishes and saves the file(s) to disk. It defaults to false and is only safe for small documents — translation often takes minutes and your MCP client may time the request out first.
• max_poll_attempts (default 120, one poll every poll_interval_ms, default 3000) is a single budget shared across the upload and translation phases.
• Timeout is configurable via BLUENTE_API_TIMEOUT_MS.
• For production, use separate API keys per environment.

🔒 Data handling & privacy

• Documents you translate are uploaded to Bluente’s API (api.bluente.com by default) for processing. Do not translate documents you are not permitted to send to a third-party service.
• The AI model controls the tools. When run locally (stdio), file_path lets the model read any file your user account can read and upload it to Bluente, and output_path lets it write downloaded files to any writable path. Review tool calls in your MCP client before approving them, especially when working with untrusted documents — a malicious document could try to instruct the model to misuse these tools.
• Translated output returned by tools (file contents, status payloads) enters your AI client’s context and is therefore visible to your LLM provider.
• Your API key stays on your machine: it is read from the environment and sent only as an Authorization header to the configured Bluente API base URL. It is never logged or included in tool responses.

🧑‍💻 Local development & contributing

To run the server from source, report vulnerabilities, or contribute, see the GitHub repository — it covers local setup, architecture, the contribution guide, and the security disclosure policy.

☁️ Hosted MCP Server