bluente-translate-mcp-server

`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:

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