Skip to main content

Smartling CLI MCP: File-Based Translation Workflows with AI Tools

This article covers the local Docker-based MCP integration for file-based workflows. If you are looking for the cloud-hosted remote MCP server (which handles text queries, project management, and account data), see Smartling MCP Server: Connect Your AI Chat Tools to Smartling.

Overview

The smartling-cli-mcp Docker image lets AI tools such as Claude Desktop, Claude Code, Cursor, or any MCP-compatible client perform file-based translation workflows with Smartling directly from your local machine. It wraps the Smartling CLI tool inside a Docker container that exposes it as a Model Context Protocol (MCP) server.

The MCP server is a thin wrapper around smartling-cli and can only do what the CLI supports. Refer to the smartling-cli documentation for the full list of capabilities and limitations.

Why there are two MCP options

Smartling offers two ways to connect AI tools to Smartling via MCP. Each one is designed for a different type of workflow:

Feature

Smartling Remote MCP

smartling-cli-mcp (Docker)

Runs where?

Smartling's cloud servers

Your local machine (Docker)

File uploads?

No — blocked by MCP security

Yes — files mounted locally

Best for

Account data, text queries, project management

File-based translation workflows (upload/download)

Setup

API key + remote URL config

Docker + API credentials + local file mount

The key limitation of the remote MCP server is a security restriction on uploading files to remote servers: remote MCP servers are not permitted to receive file uploads from AI client tools. This means you cannot use the remote server to submit translation files, download translated content, or run any workflow that involves moving files to or from Smartling.

The smartling-cli-mcp Docker image solves this by running entirely on your own computer. Because the container has direct access to your local file system (via a mounted directory), your AI tool can read and write files freely, then use the Smartling CLI commands inside the container to send those files to and from Smartling's APIs.

Available tools

Once connected, your AI client can use the following 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

The smartling-cli tool supports project management, file upload/download, translation status, and machine translation commands. See Available commands below for the full reference.

Prerequisites

Before you begin, make sure you have the following:

  • Docker Desktop installed and running on your machine (download Docker)

  • A Smartling account with API credentials (User ID and Secret)

  • Your Smartling Project ID

  • An MCP-compatible AI client such as Claude Desktop, Claude Code, Cursor, or Windsurf

Your Smartling API credentials can be found in your Smartling account under Account Settings > API. Your Project ID appears in the URL when you open a project in the Smartling dashboard.

Setup

Step 1: Pull the Docker image (optional)

Open a terminal and run the following command to download the latest image from Docker Hub:

docker pull smartlinginc/smartling-cli-mcp

This step is optional as most MCP clients (e.g., Claude Desktop) will automatically pull the image the first time they run the Docker command. However, pulling it manually first can help you verify that Docker is installed and working correctly before you move on to configuration.

Step 2: Create a local working directory

Create a folder on your computer that will hold your translation files. The container will mount this folder at /smartling. For example:

mkdir ~/smartling-files

You can use any folder you like. Make a note of its full path, you will need it in the next step.

Step 3: Configure your AI client

Add an entry to your AI client's MCP configuration file. The exact file location varies by client:

AI client

Config file location

Claude Desktop (macOS)

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json

Claude Code

.claude/settings.json in your project root (or run /mcp in Claude Code)

Cursor / Windsurf

See your client's MCP documentation for the config file path.

Add the following block to the mcpServers section of your config file. Replace the placeholder values with your actual credentials and folder path:

{
  "mcpServers": {
    "smartling": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SMARTLING_USER_ID",
        "-e", "SMARTLING_SECRET",
        "-e", "SMARTLING_PROJECT_ID",
        "-v", "/path/to/your/local/folder:/smartling",
        "smartlinginc/smartling-cli-mcp"
      ],
      "env": {
        "SMARTLING_USER_ID": "your-user-id",
        "SMARTLING_SECRET": "your-secret",
        "SMARTLING_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Replace your-user-id, your-secret, and your-project-id with your Smartling API credentials and project ID. Replace /path/to/your/local/folder with the full path to the directory you created in Step 2 (e.g., /Users/yourname/smartling-files on macOS).

The volume mount must map to /smartling inside the container. The smartling-ls and smartling-cat tools only work within that path.

Optional: Custom smartling.yml

If you use a smartling.yml configuration file (e.g., with file type mappings), you can mount it into the container by adding an extra volume mount to the args array:

"-v", "/path/to/your/smartling.yml:/app/smartling.yml"

Step 4: Restart your AI client

Save the config file and fully restart your AI client. It will launch the Docker container automatically when it starts. You should see the Smartling CLI MCP listed as a connected tool.

Usage examples

Once the integration is set up, you can ask your AI tool to perform file-based Smartling tasks using natural language. The AI will translate your request into the appropriate CLI commands and execute them inside the container.

  • "List my Smartling projects"

  • "Show files available for translation"

  • "Push /smartling/en/strings.json to Smartling"

  • "Pull Spanish translations for all JSON files"

  • "Check translation status for my project"

  • "Machine translate /smartling/en/strings.json to French"

  • "Download the French and German translations of homepage.json into my local folder"

Available commands

The smartling-cli tool exposes the following command groups:

Projects

  • projects list — List all projects in the account

  • projects info — Show details about the current project

  • projects locales — List target locales

Files

  • files list — List files in the project

  • files push <file> — Upload a file for translation

  • files pull — Download translated files

  • files delete — Delete files

  • files rename — Rename a file URI

  • files status — Show translation progress

Machine translation

  • mt detect — Detect source language of files

  • mt translate — Machine translate files to target locales

For the full command reference with all flags and options, see the smartling-cli wiki.

Troubleshooting

Problem

What to check

AI client does not see the Smartling tool

Ensure Docker Desktop is running. Fully restart the AI client after saving the config file.

Authentication errors

Double-check SMARTLING_USER_ID and SMARTLING_SECRET in the env block of your config. Ensure there are no extra spaces or quotes.

Files not found by the container

Verify the -v mount path in your config matches the exact local folder path where your files are stored. The path must map to /smartling inside the container.

docker: command not found

Install Docker Desktop from docker.com and ensure it is running before starting your AI client.

Container starts but commands fail

Verify your Project ID is correct and that your API credentials have the necessary permissions.

Related resources

Related Articles
Did this answer your question?