Skip to main content
Glama
smartling-mcp-docker

smartling-mcp-docker

Official
by Smartling

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

smartling-cli

Run any smartling-cli command (projects, files, mt)

smartling-ls

List files in /smartling or a subdirectory

smartling-cat

Print the contents of a file inside /smartling

Setup

1. Pull the image

docker pull smartlinginc/smartling-cli-mcp

2. 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 /smartling inside the container. The smartling-ls and smartling-cat tools only work within that path.

SMARTLING_ACCOUNT_ID is 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 ID

Full documentation: smartling-cli wiki

Available Tools

3 tools
smartling-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

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      An MCP server for processing XLIFF and TMX translation files, enabling parsing, validation, and manipulation of translation units in localization workflows.
      9
      3
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that wraps the Tolgee localization platform API, enabling LLMs to manage translation projects, keys, translations, languages, and related workflows.
      27
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for translation and localization workflows. It exposes tools for glossary lookup, translation memory reuse, segment alignment, and demo multicloud translation.
      -