{"id":45398148,"url":"https://github.com/NimbleBrainInc/mcp-deepl","last_synced_at":"2026-03-06T20:01:34.419Z","repository":{"id":318838238,"uuid":"1073131503","full_name":"NimbleBrainInc/mcp-deepl","owner":"NimbleBrainInc","description":"DeepL MCP Server","archived":false,"fork":false,"pushed_at":"2026-02-22T07:52:56.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-22T13:42:43.680Z","etag":null,"topics":["deepl","mcp","mcpb","nimblebrain","nimbletools"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NimbleBrainInc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T16:58:59.000Z","updated_at":"2026-02-22T07:52:59.000Z","dependencies_parsed_at":"2025-10-16T16:16:27.191Z","dependency_job_id":"da114432-9baf-495a-b619-f22e07bfd768","html_url":"https://github.com/NimbleBrainInc/mcp-deepl","commit_stats":null,"previous_names":["nimblebraininc/mcp-deepl"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/NimbleBrainInc/mcp-deepl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-deepl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-deepl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-deepl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-deepl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NimbleBrainInc","download_url":"https://codeload.github.com/NimbleBrainInc/mcp-deepl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NimbleBrainInc%2Fmcp-deepl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30195529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deepl","mcp","mcpb","nimblebrain","nimbletools"],"created_at":"2026-02-21T19:44:50.174Z","updated_at":"2026-03-06T20:01:34.409Z","avatar_url":"https://github.com/NimbleBrainInc.png","language":"Python","funding_links":[],"categories":["Utilities"],"sub_categories":[],"readme":"# MCP Server DeepL\n\n[![NimbleTools Registry](https://img.shields.io/badge/NimbleTools-Registry-green)](https://github.com/nimbletoolsinc/mcp-registry)\n[![NimbleBrain Platform](https://img.shields.io/badge/NimbleBrain-Platform-blue)](https://www.nimblebrain.ai)\n[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord\u0026logoColor=white)](https://www.nimblebrain.ai/discord?utm_source=github\u0026utm_medium=readme\u0026utm_campaign=mcp-deepl\u0026utm_content=discord-badge)\n\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/NimbleBrainInc/mcp-deepl/actions/workflows/ci.yaml/badge.svg)](https://github.com/NimbleBrainInc/mcp-deepl/actions)\n\n\n## About\n\n**MCP Server - DeepL** is a production-ready Model Context Protocol (MCP) server that provides\nseamless integration with [Deepl's](https://www.deepl.com/) industry-leading neural machine translation API.\nBuilt with enterprise-grade architecture and strict type safety, this server enables AI assistants\nand agents to translate text and documents across 30+ languages, detect languages, manage custom\nglossaries for consistent terminology, and leverage DeepL's advanced features like formality\ncontrol and context-aware translations—all through a type-safe, async-first interface powered by FastMCP.\n\n\n## Features\n\n- **Official Client**: Built on the official `deepl-python` library for reliability\n- **Full API Coverage**: Complete implementation of DeepL API (translation, glossaries, usage tracking)\n- **Strongly Typed**: All responses use Pydantic models for type safety\n- **Dual Transport**: Supports both stdio and HTTP (streamable-http) modes\n- **Async/Await**: Async wrapper for seamless MCP integration\n- **Type Safe**: Full mypy strict mode compliance\n- **Production Ready**: Docker support, comprehensive tests, CI/CD pipeline\n- **Developer Friendly**: Makefile commands, auto-formatting, fast feedback\n- **High-Quality Translation**: Superior to Google Translate in quality\n- **30+ Languages**: European and Asian languages\n- **Document Translation**: PDF, DOCX, PPTX, XLSX, HTML, TXT\n- **Custom Glossaries**: Consistent terminology across translations\n- **Formality Control**: Formal/informal tone for supported languages\n\n## Architecture\n\nThis server follows MCP Server Architecture:\n\n```\nsrc/mcp_deepl/\n├── __init__.py         # Package initialization\n├── server.py           # FastMCP server with tool definitions\n├── api_client.py       # Async wrapper around official DeepL Python client\n└── api_models.py       # Pydantic models for type safety\n\ntests/                  # Unit tests with pytest + AsyncMock\ne2e/                    # End-to-end Docker integration tests\n```\n\n**Key Implementation Details:**\n- Uses the official `deepl-python` library for reliable API communication\n- Wraps the official client with async methods for MCP compatibility\n- Maintains full type safety with Pydantic models\n- Supports all DeepL API features including glossaries and document translation\n\n## Installation\n\n### Using uv (recommended)\n\n```bash\n# Install package\nuv pip install -e .\n\n# Install with dev dependencies\nuv pip install -e . --group dev\n```\n\n### Traditional pip\n\n```bash\npip install -e .\n```\n\n## Configuration\n\n1. Copy the example environment file:\n\n```bash\ncp .env.example .env\n```\n\n2. Edit `.env` and add your DeepL API key:\n\n```bash\nDEEPL_API_KEY=your_api_key_here\n```\n\n**How to get credentials:**\n\n1. Go to [deepl.com/pro-api](https://www.deepl.com/pro-api)\n2. Sign up for an account (Free or Pro)\n3. Go to Account Settings\n4. Find your API key under \"Authentication Key for DeepL API\"\n5. Copy the key and store as `DEEPL_API_KEY`\n\n**API Key Format:**\n\n- Free tier keys end with `:fx` (e.g., `abc123:fx`)\n- Pro keys do not have the `:fx` suffix\n- The server automatically detects which endpoint to use\n\nThe `.env` file is automatically loaded when the server starts.\n\n## Running the Server\n\n### Stdio Mode (for Claude Desktop)\n\n```bash\nmake run-stdio\n# or\nuv run fastmcp run src/mcp_deepl/server.py\n```\n\n### HTTP Mode\n\n```bash\nmake run-http\n# or\nuv run uvicorn mcp_deepl.server:app --host 0.0.0.0 --port 8000\n\n# Test the server is running\nmake test-http\n```\n\n### Docker\n\n```bash\n# Build image locally\nmake docker-build\n\n# Build and push multi-platform image (amd64 + arm64)\nmake release VERSION=1.0.0\n\n# Run container\nmake docker-run\n```\n\n## Claude Desktop Configuration\n\nAdd to your Claude Desktop config file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n### Option 1: HTTP Mode (Recommended)\n\nFirst, start the HTTP server:\n\n```bash\nmake run-http\n```\n\nThen add this to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"deepl\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"http://localhost:8000/mcp\"\n      ]\n    }\n  }\n}\n```\n\n**Benefits**: Better performance, easier debugging, can be deployed remotely\n\n### Option 2: Stdio Mode\n\n```json\n{\n  \"mcpServers\": {\n    \"deepl\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"/absolute/path/to/mcp-deepl\",\n        \"run\",\n        \"fastmcp\",\n        \"run\",\n        \"src/mcp_deepl/server.py\"\n      ]\n    }\n  }\n}\n```\n\n## Available MCP Tools\n\n### Text Translation\n\n- `translate_text(text, target_lang, ...)` - Translate text between languages\n- `translate_with_glossary(text, target_lang, glossary_id, ...)` - Translate using custom glossary\n\n### Language Detection and Info\n\n- `detect_language(text)` - Detect the language of text\n- `list_languages(language_type)` - List all supported languages\n\n### Usage Tracking\n\n- `get_usage()` - Get API usage statistics\n\n### Glossaries\n\n- `list_glossaries()` - List custom glossaries\n- `create_glossary(name, source_lang, target_lang, entries)` - Create custom glossary\n- `get_glossary(glossary_id)` - Get glossary details\n- `delete_glossary(glossary_id)` - Delete a glossary\n\n### Document Translation\n\n- `translate_document(document_path, target_lang, ...)` - Translate entire documents\n- `get_document_status(document_id, document_key)` - Check translation status\n- `download_translated_document(document_id, document_key)` - Download translated document\n\n## Development\n\n### Quick Commands\n\n```bash\nmake help          # Show all available commands\nmake install       # Install dependencies\nmake dev-install   # Install with dev dependencies\nmake format        # Format code with ruff\nmake lint          # Lint code with ruff\nmake typecheck     # Type check with mypy\nmake test          # Run tests with pytest\nmake test-cov      # Run tests with coverage\nmake test-e2e      # Run E2E Docker tests (requires Docker)\nmake test-http     # Test HTTP server is running\nmake check         # Run all checks (lint + typecheck + test)\nmake clean         # Clean up artifacts\nmake all           # Full workflow (clean + install + format + check)\n```\n\n### Running Tests\n\n```bash\n# Run unit tests\nmake test\n\n# Run with coverage report\nmake test-cov\n\n# Run E2E Docker tests (requires Docker, not run in CI)\nmake test-e2e\n\n# Run specific test file\nuv run pytest tests/test_server.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nmake format\n\n# Lint code\nmake lint\n\n# Fix linting issues automatically\nmake lint-fix\n\n# Type check\nmake typecheck\n\n# Run all checks\nmake check\n```\n\n### Docker Commands\n\n```bash\n# Build local image\nmake docker-build\n\n# Build and push multi-platform image\nmake release VERSION=1.0.0\n\n# Run container\nmake docker-run\n```\n\n**Multi-Platform Build Setup** (first time only):\n\n```bash\n# Create and use a new buildx builder\ndocker buildx create --name multiplatform --use\n\n# Verify the builder\ndocker buildx inspect --bootstrap\n```\n\nThe `release` command builds for both `linux/amd64` and `linux/arm64` architectures and pushes directly to your container registry.\n\n## Health Check \u0026 Troubleshooting\n\nThe server exposes a health check endpoint at `/health`:\n\n```bash\ncurl http://localhost:8000/health\n# {\"status\":\"healthy\",\"service\":\"mcp-deepl\"}\n\n# Or use the Makefile command\nmake test-http\n```\n\n### Troubleshooting HTTP Mode\n\nIf Claude Desktop can't connect to the server:\n\n1. **Check server is running**: `make test-http`\n2. **Verify port**: Ensure port 8000 is not in use by another service\n3. **Check logs**: Look at the server output for any errors\n4. **Test MCP endpoint**: `curl http://localhost:8000/` should return MCP protocol info\n5. **Verify .env**: Ensure `DEEPL_API_KEY` is set in your `.env` file\n\n### Changing the Port\n\nTo use a different port (e.g., 9000):\n\n```bash\nuv run uvicorn mcp_deepl.server:app --host 0.0.0.0 --port 9000\n```\n\nThen update your Claude Desktop config to use `http://localhost:9000/mcp`\n\n## Rate Limits\n\n**Free Tier:**\n\n- 500,000 characters per month\n- Suitable for testing and small projects\n\n**Pro Plans:**\n\n- Unlimited characters based on plan\n- Higher priority processing\n- Additional features\n\nMonitor usage with `get_usage()` tool.\n\n## Supported Languages\n\n**European Languages:**\nBulgarian (BG), Czech (CS), Danish (DA), German (DE), Greek (EL), English (EN), Spanish (ES), Estonian (ET), Finnish (FI), French (FR), Hungarian (HU), Indonesian (ID), Italian (IT), Lithuanian (LT), Latvian (LV), Dutch (NL), Polish (PL), Portuguese (PT), Romanian (RO), Russian (RU), Slovak (SK), Slovenian (SL), Swedish (SV), Turkish (TR), Ukrainian (UK)\n\n**Asian Languages:**\nChinese (ZH), Japanese (JA), Korean (KO)\n\n## Example Usage\n\n### Simple Translation\n\n```python\n# Translate text\nresult = await translate_text(\n    text=\"Hello, world!\",\n    target_lang=\"DE\"\n)\n\n# With formality control\nresult = await translate_text(\n    text=\"How are you?\",\n    target_lang=\"DE\",\n    formality=\"more\"  # Formal German\n)\n```\n\n### Using Glossaries\n\n```python\n# Create glossary for consistent terminology\nglossary = await create_glossary(\n    name=\"Product Terms\",\n    source_lang=\"EN\",\n    target_lang=\"DE\",\n    entries={\n        \"smartphone\": \"Smartphone\",\n        \"tablet\": \"Tablet-PC\",\n        \"app\": \"App\"\n    }\n)\n\n# Translate using glossary\nresult = await translate_with_glossary(\n    text=\"Our new smartphone app\",\n    target_lang=\"DE\",\n    glossary_id=glossary.glossary_id\n)\n```\n\n### Language Detection\n\n```python\n# Detect language\nresult = await detect_language(text=\"Bonjour le monde\")\n# Returns: {\"detected_language\": \"FR\", ...}\n```\n\n## Requirements\n\n- Python 3.13+\n- deepl (official DeepL Python client)\n- fastapi\n- fastmcp\n- pydantic\n- python-dotenv\n- uvicorn\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n## License\n\nMIT\n\n## API Documentation\n\nPart of the [NimbleTools Registry](https://github.com/nimbletoolsinc/mcp-registry) - an open source collection of production-ready MCP servers. For enterprise deployment, check out [NimbleBrain](https://www.nimblebrain.ai).\n\n- [DeepL API Documentation](https://www.deepl.com/docs-api)\n- [Text Translation](https://www.deepl.com/docs-api/translate-text/)\n- [Document Translation](https://www.deepl.com/docs-api/translate-documents/)\n- [Glossaries](https://www.deepl.com/docs-api/glossaries/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNimbleBrainInc%2Fmcp-deepl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNimbleBrainInc%2Fmcp-deepl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNimbleBrainInc%2Fmcp-deepl/lists"}