smartling-mcp-docker
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smartling-mcp-docker List my Smartling projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Smartling MCP Docker
A Docker-based MCP (Model Context Protocol) server that wraps smartling-cli — the official Smartling command-line tool. This MCP server is a thin wrapper and can only do what smartling-cli supports. Refer to the smartling-cli documentation for the full list of capabilities and limitations.
Requirements
Docker
Smartling account credentials
Related MCP server: tolgee-mcp
Tools
Tool | Description |
| Run any |
| List files in |
| Print the contents of a file inside |
Setup
1. Pull the image
docker pull smartlinginc/smartling-cli-mcp2. Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"smartling": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "SMARTLING_USER_ID",
"-e", "SMARTLING_SECRET",
"-e", "SMARTLING_PROJECT_ID",
"-e", "SMARTLING_ACCOUNT_ID",
"-v", "/absolute/path/to/your/project:/smartling",
"smartlinginc/smartling-cli-mcp"
],
"env": {
"SMARTLING_USER_ID": "your-user-id",
"SMARTLING_SECRET": "your-secret",
"SMARTLING_PROJECT_ID": "your-project-id",
"SMARTLING_ACCOUNT_ID": "your-account-id"
}
}
}
}Important: The volume mount must map to
/smartlinginside the container. Thesmartling-lsandsmartling-cattools only work within that path.
SMARTLING_ACCOUNT_IDis required for most commands (files push,projects list,glossaries *, etc.). The MCP server injects it automatically as-a <account-id>— it is not natively supported by the CLI as an env var.
To use a custom smartling.yml (e.g. with file type mappings), mount it into /app/smartling.yml inside the container:
"-v", "/absolute/path/to/your/project:/smartling",
"-v", "/absolute/path/to/smartling.yml:/app/smartling.yml",Restart Claude Desktop after editing the config.
3. Configure Claude Code
Add to your project's .claude/settings.json or run /mcp in Claude Code:
{
"mcpServers": {
"smartling": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "SMARTLING_USER_ID",
"-e", "SMARTLING_SECRET",
"-e", "SMARTLING_PROJECT_ID",
"-e", "SMARTLING_ACCOUNT_ID",
"-v", "/absolute/path/to/your/project:/smartling",
"smartlinginc/smartling-cli-mcp"
],
"env": {
"SMARTLING_USER_ID": "your-user-id",
"SMARTLING_SECRET": "your-secret",
"SMARTLING_PROJECT_ID": "your-project-id",
"SMARTLING_ACCOUNT_ID": "your-account-id"
}
}
}
}With a custom smartling.yml:
{
"mcpServers": {
"smartling": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "SMARTLING_USER_ID",
"-e", "SMARTLING_SECRET",
"-e", "SMARTLING_PROJECT_ID",
"-e", "SMARTLING_ACCOUNT_ID",
"-v", "/absolute/path/to/your/project:/smartling",
"-v", "/absolute/path/to/smartling.yml:/app/smartling.yml",
"smartlinginc/smartling-cli-mcp"
],
"env": {
"SMARTLING_USER_ID": "your-user-id",
"SMARTLING_SECRET": "your-secret",
"SMARTLING_PROJECT_ID": "your-project-id",
"SMARTLING_ACCOUNT_ID": "your-account-id"
}
}
}
}Usage examples
Once configured, ask Claude naturally:
"List my Smartling projects"
"Show files available for translation"
"Push /smartling/en/strings.json to Smartling with URI en/strings.json"
"Pull Spanish translations for all JSON files into /smartling"
"Check translation status for my project"
"Machine translate /smartling/en/strings.json to French"
Available smartling-cli commands
PROJECTS
projects list List all projects in the account
projects info Show details about the current project
projects locales List target locales
-s, --short Locale IDs only
--source Source locale only
--format '<go-template>' Custom output format
FILES
files list ['<mask>'] List files in project
--short URIs only
files push <file> [<uri>] Upload a file
--type <type> Override file type (e.g. json, plaintext)
-b, --branch <prefix> Add branch prefix; @auto detects git branch
--directive <directive> Set file-level directive
files pull ['<mask>'] Download translated files
--source Download source only
-l <locale> Target locale (repeatable)
files delete ['<mask>'] Delete files
files rename <old-uri> <new-uri> Rename a file URI
files status Show translation progress
MT (Machine Translation)
mt detect '<mask>' Detect source language
-s, --short Output locale code only
--output table|json Output format
mt translate '<mask>' Machine translate files
-l, --target-locale <locale> Target locale (repeatable)
--source-locale <locale> Source language (auto-detected if omitted)
--input-directory <dir> Source directory
--output-directory <dir> Output directory
GLOSSARIES
glossaries list List glossaries in the account
--name <name> Filter by name
--output simple|table|json Output format
glossaries create <name> Create a new glossary
--locale <locale> Add a locale (repeatable)
--description <text> Optional description
--verification-mode Enable verification mode
--fallback-locale <from>:<to[,to]> Fallback locale mapping (repeatable)
glossaries export <uid|name> [file] Export glossary entries to a file
--file-type csv|xlsx|tbx Export file format (required)
--tbx-version v2|v3 TBX version (required when --file-type=tbx)
--focus-locale <locale> Focus locale for the export
--locale <locale> Include locale in export (repeatable)
--skip-entries Skip glossary entries in the export
--filter-query <text> Filter entries by free-text query
--filter-entry-state <state> Filter entries by state
--filter-locale <locale> Filter by locale ID (repeatable)
--filter-entry-uid <uid> Filter by entry UID (repeatable)
--filter-missing-translation-locale Filter: locale missing a translation
--filter-present-translation-locale Filter: locale with a translation
--filter-created-date <RFC3339> Filter by created date
--filter-last-modified-date <RFC3339> Filter by last modified date
glossaries import <uid|name> <file> Import glossary from CSV/XLSX/TBX
--archive-mode Archive entries missing from the file
--media-type <type> Override media type detection
GLOBAL FLAGS
-a, --account <account-id> Override account ID
-p, --project <project-id> Override project IDFull documentation: smartling-cli wiki
Available Tools
3 toolssmartling-catA
Print the contents of a file inside /smartling to the conversation. Use this to read source files before uploading or to inspect downloaded translations.
Inputs: path (required).
smartling-cliA
Run any smartling-cli command. Pass arguments as a single string exactly as you would on the command line.
Run --help on any command or subcommand to see all available options, e.g. "files push --help" or "mt translate --help".
FILE URI CONVENTION User files are mounted at /smartling inside the container. When pushing a file, ALWAYS specify an explicit argument that strips the /smartling prefix. This ensures the file URI stored in Smartling is a clean relative path (e.g. "en/strings.json"), not an absolute container path (e.g. "/smartling/en/strings.json"). Failing to do so causes double-path issues on download: pulled files would land at /smartling/smartling/... instead of /smartling/... When pulling files, ALWAYS pass --directory /smartling so translated files are written back into the mounted directory at the correct path.
Correct push: files push /smartling/en/strings.json en/strings.json Wrong push: files push /smartling/en/strings.json ← URI becomes /smartling/en/strings.json Correct pull: files pull '.json' -l es-ES --directory /smartling Wrong pull: files pull '.json' -l es-ES ← files land in /app, not /smartling
GLOBAL FLAGS (supported by all commands) -a, --account Override account ID -p, --project Override project ID
ACCOUNT ID Most commands require an account ID. Set the SMARTLING_ACCOUNT_ID environment variable in the Docker config to inject it automatically. If not set, pass -a explicitly. Note: SMARTLING_ACCOUNT_ID is not natively supported by the CLI — this MCP server injects it as a -a flag automatically when the env var is present.
PROJECTS projects list Display all projects in the account (fields: ID, ACCOUNT, NAME, LOCALE, STATUS) projects info Show details about the current project projects locales Display all target project locales with descriptions -s, --short Show locale IDs only --source Display only the source locale --format '' Custom output format, e.g. --format='{{if .Enabled}}{{.LocaleID}}{{end}} '
FILES files list [''] List files in project --short Show URIs only --format '' Custom output format files push [] Upload a file --type Override file type detection (e.g. json, plaintext) --directive Set file-level directive -b, --branch Add branch prefix to URI; use @auto to detect git branch files pull [''] Download translated files --source Download source file only -l Target locale (repeatable: -l es-ES -l fr-FR) files delete [''] Delete files (also accepts piped URIs via -) files rename Rename a file URI in the project files status Show translation progress for all files
MT (Machine Translation) mt detect '' Detect source language of files -s, --short Output locale code only --type Override file type detection --input-directory Source directory for input files --output table|json Output format mt translate '' Machine translate files to target locale(s) -l, --target-locale Target locale (repeatable: -l es-ES -l fr) --source-locale Source language (auto-detected if omitted) --input-directory Source directory for input files --output-directory Destination directory for translated files --type Override file type detection
GLOSSARIES glossaries list List glossaries in the account --name Filter by name --output simple|table|json Output format glossaries create Create a new glossary --locale Add a locale (repeatable) --description Optional description --verification-mode Enable verification mode --fallback-locale :<to[,to]> Fallback locale mapping (repeatable) glossaries export <uid|name> [file] Export glossary entries to a file --file-type csv|xlsx|tbx Export file format (required) --tbx-version v2|v3 TBX version (required when --file-type=tbx) --focus-locale Focus locale for the export --locale Include locale in export (repeatable) --skip-entries Skip glossary entries in the export --filter-query Filter: free-text query to match entries --filter-entry-state Filter: entry state to match --filter-locale Filter: locale ID (repeatable) --filter-entry-uid Filter: entry UID (repeatable) --filter-missing-translation-locale Filter: locale missing a translation --filter-present-translation-locale Filter: locale with a translation --filter-created-date Filter: created date (e.g. 2026-01-02T15:04:05Z) --filter-last-modified-date Filter: last modified date glossaries import <uid|name> Import glossary from CSV/XLSX/TBX --archive-mode Archive entries missing from the imported file --media-type Override media type detection
EXAMPLES projects list projects locales --short projects locales --format='{{if .Enabled}}{{.LocaleID}}{{end}} ' files list files list '.json' --short files push /smartling/en/strings.json en/strings.json --type json files push /smartling/en/strings.json en/strings.json files push '.md' --type plaintext -b feature-branch files push '.md' --branch '@auto' files pull '.json' -l es-ES -l fr-FR --directory /smartling files pull --source --directory /smartling files delete '**.json' files rename old/path.json new/path.json files status mt detect document.txt mt detect '.txt' --output json mt translate document.txt -l es-ES mt translate '.txt' -l es -l fr --output-directory /smartling/translations/ glossaries list glossaries list --name "Product Terms" glossaries create "Product Terms" --locale es-ES --locale fr-FR glossaries export "Product Terms" /smartling/glossary.xlsx --file-type xlsx glossaries export "Product Terms" /smartling/glossary.tbx --file-type tbx --tbx-version v3 glossaries export "Product Terms" /smartling/glossary.csv --file-type csv --locale es-ES glossaries import "Product Terms" /smartling/glossary.xlsx glossaries import "Product Terms" /smartling/glossary.xlsx --archive-mode
Full command reference: https://github.com/Smartling/smartling-cli/wiki/Projects-command-examples https://github.com/Smartling/smartling-cli/wiki/Files-command-examples https://github.com/Smartling/smartling-cli/wiki/MT-command-examples
Inputs: args (required).
smartling-lsA
List files in a smartling working directory. Only works within /smartling. Defaults to /smartling if no path given.
Inputs: path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: smartling-cli executes arbitrary CLI commands, smartling-ls lists local files, and smartling-cat prints file contents. There is no overlap in purpose, so an agent can easily choose the right tool.
All tools share the smartling- prefix, which is consistent, but the suffixes are mixed in style: 'cli' is a noun while 'ls' and 'cat' are verb-like commands. This is a minor deviation from a strictly predictable pattern.
With only 3 tools, the set is minimal but well-scoped: the main smartling-cli tool is a comprehensive wrapper, and the two helpers cover local file needs. This is within the ideal range and avoids redundancy.
The smartling-cli tool exposes the full Smartling CLI surface (projects, files, MT, glossaries), and the helper tools provide local file interaction. There are no obvious gaps for the server's intended purpose.
Maintenance
Related MCP Connectors
Smartling MCP Server
MCP server for Crowdin — projects, files, strings, translation progress, tasks, and members.
MCP server for LingoHub — localization projects, resources, exports and repository pushes.
MCP server for Translation Services
Related MCP Servers
- AlicenseCqualityDmaintenanceAn MCP server for processing XLIFF and TMX translation files, enabling parsing, validation, and manipulation of translation units in localization workflows.93MIT
- AlicenseBqualityDmaintenanceAn MCP server that wraps the Tolgee localization platform API, enabling LLMs to manage translation projects, keys, translations, languages, and related workflows.27MIT
- FlicenseBqualityDmaintenanceMCP server for natural-language control of local Docker, covering containers, images, volumes, networks, and Compose stacks, plus security scanning and diagnostics.34-
- FlicenseNot gradedqualityDmaintenanceMCP server for translation and localization workflows. It exposes tools for glossary lookup, translation memory reuse, segment alignment, and demo multicloud translation.-