# deepl/deepl-mcp-server architecture

> Architecture diagram of the GitHub repository deepl/deepl-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepl/deepl-mcp-server
- Repository: https://github.com/deepl/deepl-mcp-server

## Overview

deepl-mcp-server is a stdio MCP server that exposes DeepL translation, document translation, rephrasing, language discovery, glossary lookup, and style-rule lookup. An MCP client invokes registered tools; handlers normalize inputs, call the DeepL client or local language utilities, and format results as MCP text content. Document translation uses local file paths and returns the output path. The architecture is based on the README and sampled source; individual DeepL SDK internals are not shown.

Main entry points: [`src/handlers.mjs`](https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs) (Tool handlers), [`src/index.mjs`](https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs) (DeepL client), [`src/tools.mjs`](https://github.com/deepl/deepl-mcp-server/blob/main/src/tools.mjs) (Tool registry), [`src/languages.mjs`](https://github.com/deepl/deepl-mcp-server/blob/main/src/languages.mjs) (Language cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP runtime"]
  node_stdio["stdio transport<br/>[index.mjs]"]
  node_server["MCP server<br/>[index.mjs]"]
  node_tools["Tool registry<br/>[tools.mjs]"]
end

subgraph group_operations["Translation operations"]
  node_handlers["Tool handlers<br/>[handlers.mjs]"]
  node_text["Text translation<br/>[handlers.mjs]"]
  node_document["Document translation<br/>[handlers.mjs]"]
  node_rephrase["Text rephrasing<br/>[handlers.mjs]"]
  node_deeplclient["DeepL client<br/>[index.mjs]"]
end

subgraph group_lookups["Language and resource lookup"]
  node_languagecache["Language cache<br/>[languages.mjs]"]
  node_languagecatalog["Language lists<br/>[languages.mjs]"]
  node_resourcequeries["Glossary and style lookup<br/>[handlers.mjs]"]
end

subgraph group_shared["Shared utilities"]
  node_content["MCP text formatting<br/>[content.mjs]"]
  node_writing["Writing options<br/>[writing.mjs]"]
end

node_client(("MCP client"))
node_deeplapi["DeepL API"]
node_localfiles["Local documents"]

node_client -->|"sends requests"| node_stdio
node_stdio -->|"carries messages"| node_server
node_server -->|"routes tool calls"| node_tools
node_server -->|"connects transport"| node_stdio
node_tools -->|"registers callbacks"| node_handlers
node_handlers -->|"handles requests"| node_text
node_handlers -->|"handles requests"| node_document
node_handlers -->|"handles requests"| node_rephrase
node_handlers -->|"handles requests"| node_resourcequeries
node_handlers -->|"gets languages"| node_languagecache
node_handlers -->|"calls API methods"| node_deeplclient
node_deeplclient -->|"sends API requests"| node_deeplapi
node_handlers -->|"passes file paths"| node_localfiles
node_deeplclient -->|"reads and writes"| node_localfiles
node_languagecache -->|"creates and caches"| node_languagecatalog
node_languagecatalog -->|"fetches languages"| node_deeplclient
node_handlers -->|"formats responses"| node_content
node_tools -->|"uses option enums"| node_writing

click node_stdio "https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs"
click node_server "https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs"
click node_tools "https://github.com/deepl/deepl-mcp-server/blob/main/src/tools.mjs"
click node_handlers "https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs"
click node_text "https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs"
click node_document "https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs"
click node_rephrase "https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs"
click node_deeplclient "https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs"
click node_languagecache "https://github.com/deepl/deepl-mcp-server/blob/main/src/languages.mjs"
click node_languagecatalog "https://github.com/deepl/deepl-mcp-server/blob/main/src/languages.mjs"
click node_resourcequeries "https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs"
click node_content "https://github.com/deepl/deepl-mcp-server/blob/main/src/content.mjs"
click node_writing "https://github.com/deepl/deepl-mcp-server/blob/main/src/writing.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_server,node_tools,node_client toneBlue
class node_handlers,node_text,node_document,node_rephrase,node_deeplclient toneAmber
class node_languagecache,node_languagecatalog,node_resourcequeries,node_deeplapi toneMint
class node_content,node_writing toneRose
class node_localfiles toneIndigo
```

## Components

### MCP runtime

- [stdio transport](https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs): `src/index.mjs`
- [MCP server](https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs): `src/index.mjs`
- [Tool registry](https://github.com/deepl/deepl-mcp-server/blob/main/src/tools.mjs): `src/tools.mjs`

### Translation operations

- [Tool handlers](https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs): `src/handlers.mjs`
- [Text translation](https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs): `src/handlers.mjs`
- [Document translation](https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs): `src/handlers.mjs`
- [Text rephrasing](https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs): `src/handlers.mjs`
- [DeepL client](https://github.com/deepl/deepl-mcp-server/blob/main/src/index.mjs): `src/index.mjs`

### Language and resource lookup

- [Language cache](https://github.com/deepl/deepl-mcp-server/blob/main/src/languages.mjs): `src/languages.mjs`
- [Language lists](https://github.com/deepl/deepl-mcp-server/blob/main/src/languages.mjs): `src/languages.mjs`
- [Glossary and style lookup](https://github.com/deepl/deepl-mcp-server/blob/main/src/handlers.mjs): `src/handlers.mjs`

### Shared utilities

- [MCP text formatting](https://github.com/deepl/deepl-mcp-server/blob/main/src/content.mjs): `src/content.mjs`
- [Writing options](https://github.com/deepl/deepl-mcp-server/blob/main/src/writing.mjs): `src/writing.mjs`

### Other components

- **MCP client**
- **DeepL API**
- **Local documents**

## Connections

- MCP client → stdio transport: sends requests
- stdio transport → MCP server: carries messages
- MCP server → Tool registry: routes tool calls
- MCP server → stdio transport: connects transport
- Tool registry → Tool handlers: registers callbacks
- Tool handlers → Text translation: handles requests
- Tool handlers → Document translation: handles requests
- Tool handlers → Text rephrasing: handles requests
- Tool handlers → Glossary and style lookup: handles requests
- Tool handlers → Language cache: gets languages
- Tool handlers → DeepL client: calls API methods
- DeepL client → DeepL API: sends API requests
- Tool handlers → Local documents: passes file paths
- DeepL client → Local documents: reads and writes
- Language cache → Language lists: creates and caches
- Language lists → DeepL client: fetches languages
- Tool handlers → MCP text formatting: formats responses
- Tool registry → Writing options: uses option enums