bluente-translate

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

Table of Contents

• 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

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

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