MCP Deepl

MCP 服务器 DeepL

  

  

关于

MCP 服务器 - DeepL 这是一个已准备好投入生产的模型上下文协议（MCP）服务器，提供 与……无缝集成 Deepl's（的） 行业领先的神经机器翻译API。 采用企业级架构和严格的类型安全性构建，该服务器支持AI助手 以及代理用于在30多种语言间翻译文本和文档、检测语言、管理自定义（设置/内容等） 术语一致性词汇表，并利用DeepL的高级功能（如正式程度调整） 通过FastMCP驱动的类型安全、以异步优先的接口，实现控制和上下文感知的翻译。

特点/特性

• 官方客户端建立在官方之上 deepl-python 可靠性库
• 完整API覆盖DeepL API的完整实现（翻译、术语库、使用追踪）
• 强类型所有响应都使用 Pydantic 模型来确保类型安全
• 双运输（或“双通道运输”）支持stdio和HTTP（流式HTTP）两种模式
• 异步/等待（Async/Await）用于实现MCP无缝集成的异步包装器
• 类型安全完全符合 mypy 严格模式要求
• 已准备好投入生产Docker支持，全面测试，CI/CD流水线
• 对开发者友好Makefile命令、自动格式化、快速反馈
• 高质量翻译质量优于谷歌翻译
• 30多种语言欧洲和亚洲语言
• 文件翻译PDF、DOCX、PPTX、XLSX、HTML、TXT
• 自定义词汇表翻译时术语保持一致
• 正式性控制对于支持的语言，采用正式/非正式的语气

建筑学

此服务器遵循MCP服务器架构：

src/mcp_deepl/
├── __init__.py         # Package initialization
├── server.py           # FastMCP server with tool definitions
├── api_client.py       # Async wrapper around official DeepL Python client
└── api_models.py       # Pydantic models for type safety

tests/                  # Unit tests with pytest + AsyncMock
e2e/                    # End-to-end Docker integration tests

关键实施细节：

• 使用官方 deepl-python 用于可靠API通信的库
• 为官方客户端封装了异步方法以实现与MCP（Modded Client Protocol，模组客户端协议）的兼容性
• 与 Pydantic 模型保持完全的类型安全性
• 支持所有DeepL API功能，包括术语库和文档翻译

安装

使用紫外线（推荐）

# Install package
uv pip install -e .

# Install with dev dependencies
uv pip install -e . --group dev

传统的pip（这里“pip”可能指某种特定术语或概念，根据上下文可具体翻译，但一般可译为“传统pip”或根据具体含义翻译）

pip install -e .

配置

1. 复制示例环境文件：

cp .env.example .env

1. 编辑 .env 并添加您的DeepL API密钥：

DEEPL_API_KEY=your_api_key_here

如何获取凭证：

1. 首选 deepl.com/pro-api 翻译为中文是：“DeepL.com 专业版 API”
2. 注册一个账户（免费版或专业版）
3. 前往账户设置
4. 在“DeepL API的身份验证密钥”下找到您的API密钥
5. 复制密钥并存储为 DEEPL_API_KEY

API密钥格式：

• 免费层级密钥以……结尾 :fx （例如。， abc123:fx)
• 专业版密钥不包含 :fx 后缀
• 服务器自动检测应使用哪个终端节点

这个（或“该”） .env 服务器启动时，文件会自动加载。

运行服务器

Stdio 模式（适用于 Claude 桌面版）

make run-stdio
# or
uv run fastmcp run src/mcp_deepl/server.py

HTTP 模式

make run-http
# or
uv run uvicorn mcp_deepl.server:app --host 0.0.0.0 --port 8000

# Test the server is running
make test-http

Docker

# Build image locally
make docker-build

# Build and push multi-platform image (amd64 + arm64)
make release VERSION=1.0.0

# Run container
make docker-run

克劳德桌面配置

在您的Claude桌面配置文件中添加：

macOS（苹果电脑操作系统）: ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%/Claude/claude_desktop_config.json

选项1：HTTP模式（推荐）

首先，启动HTTP服务器：

make run-http

然后将此添加到您的Claude桌面配置中：

{
  "mcpServers": {
    "deepl": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp"
      ]
    }
  }
}

好处性能更佳，调试更易，可远程部署

选项2：标准I/O模式（Stdio模式）

{
  "mcpServers": {
    "deepl": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-deepl",
        "run",
        "fastmcp",
        "run",
        "src/mcp_deepl/server.py"
      ]
    }
  }
}

可用的MCP工具

文本翻译

• translate_text(text, target_lang, ...) - 在不同语言之间翻译文本
• translate_with_glossary(text, target_lang, glossary_id, ...) - 使用自定义术语表进行翻译

语言检测与信息

• detect_language(text) - 检测文本的语言
• list_languages(language_type) - 列出所有支持的语言

使用追踪

• get_usage() 获取API使用统计信息

术语表

• list_glossaries() - 列出自定义术语表
• create_glossary(name, source_lang, target_lang, entries) - 创建自定义术语表
• get_glossary(glossary_id) - 获取术语表详情
• delete_glossary(glossary_id) - 删除术语表

文件翻译

• translate_document(document_path, target_lang, ...) - 翻译整份文件
• get_document_status(document_id, document_key) - 检查翻译状态
• download_translated_document(document_id, document_key) - 下载翻译后的文档

发展

快速命令

make help          # Show all available commands
make install       # Install dependencies
make dev-install   # Install with dev dependencies
make format        # Format code with ruff
make lint          # Lint code with ruff
make typecheck     # Type check with mypy
make test          # Run tests with pytest
make test-cov      # Run tests with coverage
make test-e2e      # Run E2E Docker tests (requires Docker)
make test-http     # Test HTTP server is running
make check         # Run all checks (lint + typecheck + test)
make clean         # Clean up artifacts
make all           # Full workflow (clean + install + format + check)

运行测试

# Run unit tests
make test

# Run with coverage report
make test-cov

# Run E2E Docker tests (requires Docker, not run in CI)
make test-e2e

# Run specific test file
uv run pytest tests/test_server.py -v

代码质量

# Format code
make format

# Lint code
make lint

# Fix linting issues automatically
make lint-fix

# Type check
make typecheck

# Run all checks
make check

Docker 命令

# Build local image
make docker-build

# Build and push multi-platform image
make release VERSION=1.0.0

# Run container
make docker-run

多平台构建设置 （仅限首次）：

# Create and use a new buildx builder
docker buildx create --name multiplatform --use

# Verify the builder
docker buildx inspect --bootstrap

这个（或“该”） release 为两者构建命令 linux/amd64 和 linux/arm64 架构设计，并直接推送到您的容器注册表。

健康检查与故障排除

服务器在以下路径暴露了一个健康检查端点： /health：

curl http://localhost:8000/health
# {"status":"healthy","service":"mcp-deepl"}

# Or use the Makefile command
make test-http

HTTP模式故障排除

如果Claude Desktop无法连接到服务器：

1. 检查服务器是否正在运行: make test-http
2. 验证端口确保端口8000没有被其他服务占用
3. 检查日志查看服务器输出以检查任何错误
4. 测试MCP端点： curl http://localhost:8000/ 应返回MCP协议信息
5. 验证 .env 文件确保 DEEPL_API_KEY 已设置在您的 .env 文件

更改端口

要使用不同的端口（例如，9000）：

uv run uvicorn mcp_deepl.server:app --host 0.0.0.0 --port 9000

然后更新您的Claude Desktop配置以使用 http://localhost:9000/mcp

速率限制

免费套餐：

• 每月50万个字符
• 适用于测试和小型项目

专业计划：

• 根据套餐，字符数量无限
• 优先级更高的处理
• 附加功能

监控使用情况，使用 get_usage() 工具。

支持的语言

欧洲语言： 保加利亚语（BG）、捷克语（CS）、丹麦语（DA）、德语（DE）、希腊语（EL）、英语（EN）、西班牙语（ES）、爱沙尼亚语（ET）、芬兰语（FI）、法语（FR）、匈牙利语（HU）、印尼语（ID）、意大利语（IT）、立陶宛语（LT）、拉脱维亚语（LV）、荷兰语（NL）、波兰语（PL）、葡萄牙语（PT）、罗马尼亚语（RO）、俄语（RU）、斯洛伐克语（SK）、斯洛文尼亚语（SL）、瑞典语（SV）、土耳其语（TR）、乌克兰语（UK）

亚洲语言： 中文（ZH）、日语（JA）、韩语（KO）

示例用法

简单翻译

# Translate text
result = await translate_text(
    text="Hello, world!",
    target_lang="DE"
)

# With formality control
result = await translate_text(
    text="How are you?",
    target_lang="DE",
    formality="more"  # Formal German
)

使用术语表

# Create glossary for consistent terminology
glossary = await create_glossary(
    name="Product Terms",
    source_lang="EN",
    target_lang="DE",
    entries={
        "smartphone": "Smartphone",
        "tablet": "Tablet-PC",
        "app": "App"
    }
)

# Translate using glossary
result = await translate_with_glossary(
    text="Our new smartphone app",
    target_lang="DE",
    glossary_id=glossary.glossary_id
)

语言检测

# Detect language
result = await detect_language(text="Bonjour le monde")
# Returns: {"detected_language": "FR", ...}

要求

• Python 3.13+
• DeepL（官方的DeepL Python客户端）
• FastAPI（快速API）
• fastmcp
• pydantic（一个用于数据验证和设置管理的Python库）
• python-dotenv
• Uvicorn（注：Uvicorn是一个用于运行ASGI应用的服务器，常用于Python的异步Web框架中，如FastAPI）

贡献

看 \CONTRIBUTING.md\ 翻译为中文是：“贡献指南文件”或“贡献说明文档”。这个文件通常用于说明如何向项目贡献代码或内容，包括贡献的流程、规范、要求等 作为开发指南。

许可证

麻省理工学院（MIT）

API 文档

• DeepL API 文档
• 文本翻译
• 文件翻译
• 术语表