README.md•7.19 kB
# TartuNLP MCP Server
[](https://github.com/tbitu/tartunlp-mcp/pkgs/container/tartunlp-mcp)
[](https://www.python.org/)
[](LICENSE)
A Model Context Protocol (MCP) server that provides seamless access to [TartuNLP translation services](https://api.tartunlp.ai/) from the University of Tartu. This server enables AI assistants and applications to perform high-quality machine translation across 700+ language pairs, with specialized support for European and Finno-Ugric languages.
## Features
- 🌍 **700+ Language Pairs** - Comprehensive translation coverage including European languages and rare Finno-Ugric languages
- 🚀 **Docker-First Deployment** - Pre-built Docker images for easy deployment across platforms
- 🔧 **Simple Integration** - Standard MCP protocol support for seamless integration with AI assistants
- 🎯 **Specialized Language Support** - Expert translation for Estonian, Finnish, Sami languages, and other minority languages
- 📦 **Zero Configuration** - Works out of the box with sensible defaults
## Quick Start
### Using Docker (Recommended)
The easiest way to use this MCP server is via Docker. Pre-built images are automatically published to GitHub Container Registry and support both `linux/amd64` and `linux/arm64` platforms.
Add this configuration to your MCP settings file (e.g., `~/.vscode-server/data/User/mcp.json` or Claude Desktop config):
```json
{
"mcpServers": {
"TartuNLP": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/tbitu/tartunlp-mcp:latest"
]
}
}
}
```
> [!TIP]
> The Docker approach requires no local Python installation or dependency management. The image is kept minimal (~150MB) for fast downloads.
### Using Python (Local Development)
For local development or if you prefer not to use Docker:
1. **Install the package:**
```bash
pip install -e .
```
2. **Add to your MCP configuration:**
**Linux/Mac:**
```json
{
"mcpServers": {
"TartuNLP": {
"command": "python3",
"args": ["-m", "tartunlp_mcp_server"]
}
}
}
```
**Windows:**
```json
{
"mcpServers": {
"TartuNLP": {
"command": "python",
"args": ["-m", "tartunlp_mcp_server"]
}
}
}
```
> [!NOTE]
> Requires Python 3.8 or higher. Use `python3` on systems where both Python 2 and 3 are installed.
## Available Tools
Once configured, the MCP server exposes the following tools to AI assistants:
### `translate_text`
Translate text between any supported language pair.
**Parameters:**
- `text` (string): The text to translate
- `source_lang` (string): Source language code (e.g., 'eng', 'est', 'fin')
- `target_lang` (string): Target language code (e.g., 'eng', 'est', 'fin')
- `model` (string, optional): Specific translation model/domain to use
### `get_supported_languages`
Retrieve the complete list of supported language pairs and available translation models.
**Returns:** List of all 700+ available translation pairs with source/target language information.
## Development
### Local Testing
```bash
# Install dependencies
pip install -e .
# Run the server locally
python -m tartunlp_mcp_server
```
### Building Docker Images
```bash
# Build locally
docker build -t tartunlp-mcp .
# Test the Docker image
docker run -i --rm tartunlp-mcp
```
### CI/CD
Docker images are automatically built and published to GitHub Container Registry on every push to the `main` branch. The workflow:
1. Builds multi-platform images (linux/amd64, linux/arm64)
2. Tags images with branch name, commit SHA, and `latest`
3. Publishes to `ghcr.io/tbitu/tartunlp-mcp`
See [`.github/workflows/docker-build-push.yml`](.github/workflows/docker-build-push.yml) for details.
## Supported Languages
The server supports **700 translation pairs** as provided by TartuNLP's API. Based on the actual API response, the supported language pairs are:
### Core European Languages with Full Coverage
- **English (eng)** ↔ Estonian, German, Lithuanian, Latvian, Finnish, Russian, Ukrainian + all minority languages
- **Estonian (est)** ↔ English, German, Lithuanian, Latvian, Finnish, Russian, Ukrainian + all minority languages
- **Finnish (fin)** ↔ English, Estonian, German, Lithuanian, Latvian, Russian + all minority languages
- **Russian (rus)** ↔ English, Estonian, German, Lithuanian, Latvian, Finnish, Ukrainian + all minority languages
- **Latvian (lav)** ↔ English, Estonian, German, Lithuanian, Finnish, Russian + all minority languages
### Limited European Language Support
- **German (ger)** ↔ English, Estonian, Lithuanian, Latvian, Finnish, Russian (no minority language pairs)
- **Lithuanian (lit)** ↔ English, Estonian, German, Latvian, Finnish, Russian (no minority language pairs)
- **Ukrainian (ukr)** ↔ English, Estonian, Russian only
- **Norwegian (nor)** ↔ All minority languages only (no major European languages except through minority languages)
- **Hungarian (hun)** ↔ All minority languages only (no major European languages except through minority languages)
### Finno-Ugric & Minority Languages (Full Matrix)
All minority languages can translate to/from each other and to/from: eng, est, fin, rus, lav, nor, hun
- **Karelian (krl)** - Karelian language
- **Ludian (lud)** - Ludic language
- **Veps (vep)** - Vepsian language
- **Livonian (liv)** - Livonian language (critically endangered)
- **Võro (vro)** - Võro language (South Estonian)
- **Mari (mhr)** - Eastern Mari
- **Hill Mari (mrj)** - Western Mari
- **Udmurt (udm)** - Udmurt language
- **Komi-Permyak (koi)** - Komi-Permyak language
- **Komi-Zyrian (kpv)** - Komi-Zyrian language
- **Moksha (mdf)** - Moksha Mordvin
- **Erzya (myv)** - Erzya Mordvin
- **Olonets (olo)** - Olonets Karelian
- **Mansi (mns)** - Mansi language
- **Khanty (kca)** - Khanty language
### Sami Languages (Full Matrix)
- **Southern Sami (sma)** - Åarjelsaemien gïele
- **Northern Sami (sme)** - Davvisámegiella
- **Inari Sami (smn)** - Anarâškielâ
- **Skolt Sami (sms)** - Sääʹmǩiõll
- **Lule Sami (smj)** - Julevsámegiella
### Key Translation Patterns
**Major European Language Pairs:**
- eng ↔ est, ger, lit, lav, fin, rus, ukr
- est ↔ eng, ger, lit, lav, fin, rus, ukr
- fin ↔ eng, est, ger, lit, lav, rus
- rus ↔ eng, est, ger, lit, lav, fin, ukr
- lav ↔ eng, est, ger, lit, fin, rus
- ger ↔ eng, est, lit, lav, fin, rus (limited)
- lit ↔ eng, est, ger, lav, fin, rus (limited)
- ukr ↔ eng, est, rus (very limited)
**Minority Language Hub:**
All 20 minority/indigenous languages form a complete translation matrix with each other and connect to: eng, est, fin, rus, lav, nor, hun
**Note:** The exact language pairs are determined by TartuNLP's API and may be updated. Use the `get_supported_languages` tool to get the current list.
## Tools
- `translate_text`: Translate text between supported languages
- `get_supported_languages`: List all supported language pairs