DeepL MCP Server

DeepL MCP 服务

一个通过 DeepL API 提供高质量翻译能力的 MCP（Model Context Protocol）服务。

功能

此服务提供 24 个用于操作 DeepL 的工具：

工具	描述	必需参数
translate_text	翻译文本，可配置正式程度、上下文、术语表、模型、标签处理、风格、翻译记忆库和自定义指令	text、target_lang
rephrase_text	使用 DeepL Write 提升文本清晰度和风格，可选写作风格和语气	text
get_source_languages	列出 v2 源语言	—
get_target_languages	列出 v2 目标语言及正式程度支持信息	—
get_usage	获取 API 使用统计信息	—
get_languages_v3	按产品检索 beta v3 支持的语言及功能元数据	—
get_language_products_v3	检索 beta v3 语言产品及功能规则	—
get_glossary_language_pairs	列出术语表支持的语言对	—
list_glossaries	列出 v3 术语表	—
get_glossary	检索 v3 术语表元数据	glossary_id
get_glossary_entries	检索术语表词典条目	glossary_id
create_glossary	创建 v3 多语言术语表	name、dictionaries
delete_glossary	删除 v3 术语表	glossary_id
list_translation_memories	列出账户可用的 v3 翻译记忆库	—
list_style_rules	列出 v3 风格规则列表	—
get_style_rule	检索 v3 风格规则列表	style_id
create_style_rule	创建 v3 风格规则列表	name、language
update_style_rule	更新 v3 风格规则列表名称	style_id、name
delete_style_rule	删除 v3 风格规则列表	style_id
request_voice_session	请求 DeepL Voice 实时 WebSocket 会话	source_media_content_type、target_languages
reconnect_voice_session	请求替换 DeepL Voice 实时令牌	—
upload_document	上传本地文件以进行文档翻译	file_path、target_lang
get_document_status	检查文档翻译状态	document_id、document_key
download_document	将翻译后的文档下载到本地路径	document_id、document_key、output_path

翻译功能

• 新一代模型选择 — 使用 model_type 值，例如 quality_optimized 或 prefer_quality_optimized
• 正式程度控制 — 调整正式或非正式场景下的语气
• 上下文参数 — 提供额外上下文以提升准确性（不计费）
• 术语表支持 — 创建、列出、查看、使用和删除 DeepL v3 术语表
• 批量翻译 — 在单个请求中翻译多段文本
• 保留格式 — 保持原文格式
• HTML/XML 标签处理 — 使用 tag_handling、tag_handling_version、ignore_tags、splitting_tags 等选项
• 计费信息可见 — 使用 show_billed_characters 在翻译响应中包含计费字符数
• 文档翻译 — 上传、轮询并下载翻译后的文件
• v3 语言元数据 — 检索特定产品的语言支持和功能规则
• 翻译记忆库 — 列出账户翻译记忆库，并在翻译请求中使用
• 风格规则 — 列出、创建、查看、重命名、删除和使用风格规则列表
• 语音会话设置 — 请求或重新连接 DeepL Voice 实时 WebSocket 会话；音频流通过返回的 WebSocket URL 进行传输
• DeepL Write 选项 — 在套餐支持 Write API 时，使用 writing_style 和 tone 改写文本
• 句子拆分控制 — 控制句子的拆分方式

API 类型自动检测

服务器会根据密钥格式自动检测你使用的是 Free API 还是 Pro API：

• 以 :fx 结尾的密钥 → Free API（api-free.deepl.com）
• 其他密钥 → Pro API（api.deepl.com）

前提条件

• Node.js 18+（包括 Node.js 25）
• DeepL API 密钥 — 在此注册（提供免费套餐）

快速开始

1. 克隆并构建

git clone https://github.com/watchdealer-pavel/deepl-mcp-server.git
cd deepl-mcp-server
npm install

2. 配置 MCP 客户端

将以下内容添加到 MCP 客户端配置中：

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "deepl": {
      "command": "node",
      "args": ["/path/to/deepl-mcp-server/build/index.js"],
      "env": {
        "DEEPL_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code（项目中的 .mcp.json）：

{
  "mcpServers": {
    "deepl": {
      "command": "node",
      "args": ["/path/to/deepl-mcp-server/build/index.js"],
      "env": {
        "DEEPL_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 重启 MCP 客户端

重启 Claude Desktop 或 Claude Code，以加载服务。

使用示例

基本翻译

{
  "text": "Hello, how are you?",
  "target_lang": "DE"
}

带上下文的正式翻译

{
  "text": "Thanks for your help!",
  "target_lang": "DE",
  "formality": "more",
  "context": "Business email to a client"
}

批量翻译

{
  "text": ["Hello", "Goodbye", "Thank you"],
  "target_lang": "FR"
}

检查 API 用量

使用 get_usage 查看当前配额：

{
  "character_count": 12500,
  "character_limit": 500000,
  "characters_remaining": 487500,
  "percent_used": "2.50%",
  "api_type": "Free"
}

支持的语言

源语言（省略时自动检测）

AR、BG、CS、DA、DE、EL、EN、ES、ET、FI、FR、HU、ID、IT、JA、KO、LT、LV、NB、NL、PL、PT、RO、RU、SK、SL、SV、TR、UK、ZH

目标语言

所有源语言以及以下地区变体：

• EN-GB — 英式英语
• EN-US — 美式英语
• PT-BR — 巴西葡萄牙语
• PT-PT — 欧洲葡萄牙语
• ZH-HANS — 简体中文
• ZH-HANT — 繁体中文

使用 get_target_languages 查看完整列表以及形式等级支持情况。

错误处理

服务器会处理常见的 API 错误：

• 400 — 参数无效
• 401/403 — 身份验证失败，或当前套餐不提供此功能
• 429 — 超出速率限制
• 456 — 超出配额

安全与 OSV 状态

此仓库已使用 Google 的 OSV-Scanner 扫描，并修复至无已知问题的状态。

• 最新扫描结果：0 个已知依赖项漏洞
• 报告写入 .osv/osv-report.json 和 .osv/osv-summary.md
• 修复说明见 .osv/remediation-notes.md
• 已通过升级 @modelcontextprotocol/sdk 和 axios 修复存在漏洞的直接依赖链

在本地运行扫描：

export PATH="$HOME/.local/bin:$PATH"
osv-project-scan .

开发

# Watch mode (auto-rebuild)
npm run watch

# Manual build
npm run build

# Run the server
npm start

# Test with MCP Inspector
npm run inspector

# Run live end-to-end tests against DeepL API
# Requires DEEPL_API_KEY in the environment and consumes a small number of billable characters.
npm run test:live

实时测试会测试翻译、语言列表、v3 语言元数据、翻译记忆列表，以及样式规则的列出/创建/获取/更新/删除（如可用）、语音会话请求（如可用）、用量、术语表的创建/使用/删除、文档上传/状态查询/下载，以及 DeepL Write。使用 Free API 密钥时，DeepL Write 可能会返回符合预期的套餐错误。

许可证

MIT 许可证 — 参见 LICENSE 文件。

链接

• DeepL API 文档
• DeepL Pro API — 注册以获取 API 访问权限
• Model Context Protocol — MCP 文档