# libretranslate-mcp

Translate text, detect its language, and list supported languages from an MCP client. The server runs locally over stdio and forwards requests to the LibreTranslate instance you configure.

[Set up your client](https://sourcey-libretranslate.pages.dev/guides/mcp_server/index.md) for the hosted service or your own instance. The [HTTP API](https://sourcey-libretranslate.pages.dev/api/index.md) also supports file translation and other operations beyond these three tools.

Version: 1.0.1

## detect

`TOOL detect`

Detect the language of a given text

Sends `text` as `q` to `POST /detect` on your configured instance.

Returns the first detection from the API: `language` is its language code and `confidence` is a score from 0 to 100. The tool returns one detection, even when the HTTP API supplies several. The JSON is encoded in `content[0].text`.

**Errors.** Failed requests set `isError: true` and return an `error` message in the JSON text block.

<details>
<summary>Response examples</summary>

Decoded success result:

```json
{
  "language": "en",
  "confidence": 100
}
```

Decoded failure result (`isError: true`):

```json
{
  "error": "No detection result returned"
}
```

</details>

Authentication: no security requirement declared for this operation.

Parameters:

- `text` (argument, string, required) - Text to identify.
  Type: string
  
  Text to identify.

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "detect",
    "arguments": {
        "text": "Hello"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "detect",
  "arguments": {
    "text": "Hello"
  }
});
```

### Python

```python
result = await session.call_tool("detect", arguments={
  "text": "Hello"
})
```


## translate

`TOOL translate`

Translate text from one language to another

Sends `text` as `q`, together with `source` and `target`, to `POST /translate` on your configured instance.

Returns `translatedText` and requests up to three `alternatives`. With `source: "auto"`, the API can also return `detectedLanguage`. Available alternatives depend on your instance’s models. The JSON is encoded in `content[0].text`.

**Errors.** Failed requests set `isError: true` and return an `error` message in the JSON text block. The managed service requires `LIBRETRANSLATE_API_KEY`; self-hosted instances use their own access settings.

<details>
<summary>Response examples</summary>

Decoded success result:

```json
{
  "translatedText": "Hola",
  "alternatives": [
    "Hola."
  ]
}
```

Decoded failure result (`isError: true`):

```json
{
  "error": "Unsupported target language"
}
```

</details>

Authentication: no security requirement declared for this operation.

Parameters:

- `text` (argument, string, required) - Text to translate.
  Type: string
  
  Text to translate.

- `source` (argument, string, required) - Source language code, or auto for automatic detection.
  Type: string
  
  Source language code, or auto for automatic detection.

- `target` (argument, string, required) - Target language code, such as es for Spanish.
  Type: string
  
  Target language code, such as es for Spanish.

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "translate",
    "arguments": {
        "text": "Hello",
        "source": "en",
        "target": "es"
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "translate",
  "arguments": {
    "text": "Hello",
    "source": "en",
    "target": "es"
  }
});
```

### Python

```python
result = await session.call_tool("translate", arguments={
  "text": "Hello",
  "source": "en",
  "target": "es"
})
```


## languages

`TOOL languages`

List all supported languages for translation

Calls `GET /languages` on your configured instance. No arguments are needed.

Returns an array of languages. Each entry has a `code` and an English `name`; the API can also supply `targets`, the language codes that entry can translate into. Use this list when choosing `source` and `target` for a translation. The JSON is encoded in `content[0].text`.

**Errors.** Failed requests set `isError: true` and return an `error` message in the JSON text block.

<details>
<summary>Response examples</summary>

Decoded success result:

```json
[
  {
    "code": "en",
    "name": "English",
    "targets": [
      "es"
    ]
  },
  {
    "code": "es",
    "name": "Spanish",
    "targets": [
      "en"
    ]
  }
]
```

Decoded failure result (`isError: true`):

```json
{
  "error": "Languages request failed: 503 Service Unavailable"
}
```

</details>

Authentication: no security requirement declared for this operation.

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "languages",
    "arguments": {}
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "languages",
  "arguments": {}
});
```

### Python

```python
result = await session.call_tool("languages", arguments={})
```