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:

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:

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:

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

Related resources

• Smartling MCP Server: Connect Your AI Chat Tools to Smartling
• Smartling CLI Tool 
• smartling-cli wiki — Full CLI command reference on GitHub
• smartlinginc/smartling-cli-mcp on Docker Hub — Official Docker image page