bluente-translate

Translate your documents with formatting intact in 2 minutes

Documentation

Bluente Translate MCP Server

AI-powered. Format-preserving. Built for professional document translation workflows.

bluente-translate-mcp-server is the official open-source MCP server for exposing Bluente translation capabilities to AI clients.

It wraps Bluente APIs into production-ready MCP tools so teams can automate multilingual document workflows from Claude Desktop, Cursor, and other MCP-compatible runtimes.

Why Bluente

Bluente focuses on enterprise-grade document translation where accuracy, formatting integrity, and speed matter.

From Bluente.com and Blu Translate, the core product positioning is:

AI-powered translation for professional use cases
Original layout retention for document-centric workflows
Broad language and file-type support
Security-first handling for sensitive content

This MCP server brings those capabilities into agent workflows through a standard protocol interface.

Brand Identity

This repository is maintained by Bluente and is part of Bluente's public developer ecosystem.

Company website: https://www.bluente.com
Product page: https://www.bluente.com/translator
API docs: https://www.bluente.com/docs

What You Get
Architecture
Supported Bluente APIs
MCP Tools
Quick Start
Local Development
Operational Notes
Data Handling & Privacy
Security
Roadmap
Contributing and Governance
License

What You Get

Modular Node.js MCP server with clear layering (config, client, service, tools)
One-file-per-tool implementation for maintainability
Unified tool response envelope (ok/tool/data and structured errors)
End-to-end translation workflow tool (upload -> start -> poll -> download)
CI checks and local smoke tests

Architecture

AI Client (Claude / Cursor / Agents)
            |
            | MCP (stdio)
            v
+---------------------------------------+
| Bluente Translate MCP Server          |
|                                       |
|  tools/  -> MCP tool handlers         |
|  services/ -> workflow orchestration  |
|  clients/ -> Bluente HTTP API client  |
|  config/ + lib/ -> env/errors/results |
+---------------------------------------+
            |
            | HTTPS
            v
      Bluente Translation APIs

Project layout:

src/
  clients/bluente-http-client.js
  config/env.js
  constants/api.js
  lib/errors.js
  lib/mcp-result.js
  services/translation-workflow-service.js
  tools/*.tool.js
  tools/schemas.js
  tools/register-tools.js
  server.js
  index.js
tests/smoke/core-smoke.test.js

Supported Bluente APIs

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

Reference: Bluente API Docs

MCP Tools

bluente_get_supported_languages
bluente_upload_file
bluente_get_translation_status
bluente_translate_file
bluente_download_file
bluente_translate_document_workflow

These match the tools exposed by Bluente's hosted MCP server, so a prompt or agent written against one works against the other. The differences are the two things only a local server can do: file_path as a source, and output_path for saving results to disk (the hosted server hands out download links instead).

Tool behavior notes:

Confirmation gate: bluente_translate_document_workflow is a two-call flow. The first call uploads the file and returns page_count plus a confirmation card for the user; nothing starts and no credits are deducted. Call again with the returned task_id, confirmed=true, and explicit to, to_type, and bilingual values to actually start. bluente_translate_file has no gate and starts immediately.
File sources: file_path (a file on this machine), file_url (a public link), or file_content_base64 (under 2MB).
bluente_translate_file: from and to are required when action="start" and optional when action="cancel".
to_type: pdf, word, or pptx. The workflow tool also accepts an array (e.g. ["word", "pdf"]) — extra formats are download-time conversions of the same translation and cost no extra credits.
entry / status_entry: get_status (translation progress, the default) or get_page_count (the uploaded file's page count).
Language codes: Bluente uses nonstandard codes (zh, cht, jp, kor, fra, spa, ...). Common ISO spellings (zh-CN, zh-TW, ja, ko, fr, es) are auto-aliased; call bluente_get_supported_languages for the full list.
bilingual: on keeps the original text alongside the translation; off (default) produces a clean translated document. When on, set bilingual_layout to left-right (side by side) or top-down (stacked) — these are the only two layouts Bluente supports. The numeric vertical_bilingual flag is a deprecated alias.
mode: standard (most digital documents), scanned (text) (OCR a scan into a clean text-only document), scanned (overlay) (place the translation back over the original scanned layout), or image (re-render a graphic like a brochure or poster in the target language; 5 credits per page — the only mode charged above the standard rate, scanned modes cost the same as standard). The numeric scanned 0–3 flag is a deprecated alias.
page_range (e.g. "1-3,5"): translate only selected pages; credits are charged only for those pages.
Glossary: the workflow tool always translates with the glossary enabled (matching the Bluente web product); its glossary/custom_glossary arguments are deprecated and ignored. On the raw bluente_translate_file tool the backend applies the glossary only when both glossary and custom_glossary are 1.

Success envelope:

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

Error envelope:

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

Quick Start

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

Getting an API key: log in at translate.bluente.com and go to My Files → API Keys and Webhook. 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

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

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"
      }
    }
  }
}

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

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

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.

Optional environment variables:

Variable	Default	Purpose
`BLUENTE_API_KEY`	(required)	Your Bluente API key
`BLUENTE_API_BASE_URL`	`https://api.bluente.com/api/20250924`	API base URL
`BLUENTE_API_TIMEOUT_MS`	`90000`	HTTP timeout in milliseconds

Local Development

git clone https://github.com/bluente/bluente-translate-mcp-server.git
cd bluente-translate-mcp-server
npm install
cp .env.example .env   # then set BLUENTE_API_KEY
npm start              # run the server on stdio
npm run check          # syntax check
npm test               # run tests

To point an MCP client at your local checkout, use "command": "node" with "args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"] instead of the npx config above.

Operational Notes

The workflow tool returns as soon as translation starts. Poll bluente_get_translation_status until READY, then call bluente_download_file.
auto_download=true instead blocks until the translation finishes and saves the file(s) to disk. Only safe for small documents — translation often takes minutes and your MCP client may time the request out first.
max_poll_attempts 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.

Security

Do not commit API keys or .env files.
Rotate leaked keys immediately.
Use repository private vulnerability reporting.

See SECURITY.md for disclosure policy.

Roadmap

Add text translation tools if exposed in public API docs
Add richer integration tests with API mocking
Add container image and one-command local launch profile

Contributing and Governance

Contribution guide: CONTRIBUTING.md
Security policy: SECURITY.md
Changelog: CHANGELOG.md
Code ownership: .github/CODEOWNERS

About Bluente

Bluente builds AI translation and business communication solutions for professional teams.

Website: bluente.com
Product page: Blu Translate
API documentation: bluente.com/docs

License

MIT