Translation MCP

🚀 Translation MCP Server

A text translation service based on the Model Context Protocol (MCP), supporting OpenAI and OpenAI API-compatible models.

✨ Features

• 🌍 Multilingual Support: Supports translation between over 20 major languages.
• 🤖 AI-Powered: Built on large language models compatible with OpenAI.
• 📄 Long Text Handling: Automatically chunks large documents to overcome API length limitations.
• 🔍 Language Detection: Automatically identifies the language of the input text.
• 🔌 MCP Protocol: Standardized interface for easy integration into MCP-supported applications.
• ⚡ Asynchronous Processing: High-performance asynchronous architecture based on asyncio.
• 🛠️ Flexible Configuration: Supports custom models and API endpoints.

Supported Languages

📦 Installation

Environment Requirements

• Python 3.10+
• OpenAI API key (or a compatible API service)

Install Dependencies

# Clone the project
git clone <repository-url>
cd translation_mcp

# Install dependencies using uv (recommended)
uv sync

# Or install using pip
pip install -e .

Environment Configuration

Create a .env file and configure the necessary environment variables:

# OpenAI API configuration
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional, default is the official OpenAI API
OPENAI_MODEL=gpt-3.5-turbo  # Optional, default model

💻 Usage Examples

Using as an MCP Server

This project is an MCP (Model Context Protocol) server and needs to be configured in an MCP-supported client rather than run directly.

Configuration in Claude Desktop

Add the following to the Claude Desktop configuration file:

{
  "mcpServers": {
    "translation": {
      "command": "python",
      "args": ["/path/to/translation_mcp.py"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Running with uvx (Recommended)

First, build the distribution package:

# Build the wheel package
uv build

# View the generated whl file
ls dist/

Then use it in the Claude Desktop configuration:

{
  "mcpServers": {
    "translation": {
      "command": "uvx",
      "args": ["/path/to/translation_mcp/dist/translation_mcp-0.1.0-py3-none-any.whl"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or install directly from PyPI (if published):

{
  "mcpServers": {
    "translation": {
      "command": "uvx",
      "args": ["translation-mcp"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development and Testing

# Run directly for testing
python translation_mcp.py

# Run the test suite
python test_mcp.py

MCP Tools

The server provides the following MCP tools:

1. translate_text

Translate normal text to the specified language.

Parameters:

• text (string, required): The text to be translated.
• target_language (string, required): The target language code.
• source_language (string, optional): The source language code. If not specified, it will be automatically detected.

Example:

{
  "text": "Hello, world!",
  "target_language": "zh",
  "source_language": "en"
}

2. detect_language

Detect the language of the text.

Parameters:

• text (string, required): The text to detect the language of.

Example:

{
  "text": "Bonjour le monde!"
}

3. translate_long_text

Translate long text with automatic chunking.

Parameters:

• text (string, required): The long text to be translated.
• target_language (string, required): The target language code.
• source_language (string, optional): The source language code.
• max_chunk_size (integer, optional): The maximum number of characters per text chunk, default is 2000.

Example:

{
  "text": "Very long text content...",
  "target_language": "en",
  "max_chunk_size": 1500
}

MCP Resources

translation://languages

Get a list of all supported languages, including language codes and names.

📚 Documentation

API Response Formats

Successful Response

{
  "translated_text": "Translated text",
  "source_language": "en",
  "target_language": "zh",
  "model": "gpt-3.5-turbo",
  "success": true
}

Error Response

{
  "error": "Error message",
  "success": false
}

Long Text Translation Response

{
  "translated_text": "Complete translated text",
  "source_language": "auto-detected",
  "target_language": "zh",
  "chunks_count": 3,
  "success": true
}

Configuration Options

Environment Variables

Custom Models

Supports using other services compatible with the OpenAI API:

# Use a local model service
OPENAI_BASE_URL=http://localhost:8000/v1
OPENAI_API_KEY=your_local_api_key

# Use other cloud services
OPENAI_BASE_URL=https://your-service.com/v1
OPENAI_API_KEY=your_service_api_key

🔧 Technical Details

Project Structure

translation_mcp/
├── translation_mcp.py    # Main program file
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock             # Locked dependency versions
├── MANIFEST.in         # Packaging configuration
├── .env                # Environment variable configuration
├── dist/               # Build output directory
└── README.md          # Project documentation

Building and Distribution

# Build the project
uv build

# Publish to PyPI (optional)
uv publish

Core Components

• OpenAITranslator: The core class for the translation service.
• TranslationMCPServer: The implementation of the MCP server.
• Asynchronous Processing: Asynchronous architecture based on asyncio.
• Error Handling: A comprehensive exception handling mechanism.

📄 License

MIT License

Contribution

Welcome to submit issues and pull requests!

Changelog

v0.1.0

• Initial release
• Supports basic text translation
• Supports language detection
• Supports long text chunked translation
• MCP protocol integration