DeepL MCP 服务器

一个通过 DeepL API 提供高质量翻译功能的 MCP（模型上下文协议）服务器。

功能

该服务器提供了 24 个用于 DeepL 操作的工具：

翻译特性

• 下一代模型选择 — 使用 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 类型自动检测

服务器会根据您的密钥格式自动检测您使用的是免费版还是专业版 API：

• 以 :fx 结尾的密钥 → 免费版 API (api-free.deepl.com)

• 其他密钥 → 专业版 API (api.deepl.com)

Related MCP server: GeoServer MCP Server

先决条件

• 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。免费 API 密钥可能会针对 DeepL Write 返回预期的计划错误。

许可证

MIT 许可证 — 参见 LICENSE 文件。

链接

• DeepL API 文档

• DeepL Pro API — 注册以获取 API 访问权限

• 模型上下文协议 — MCP 文档