MCP Server

Configure glot as an MCP server for code agents

Glot provides a Model Context Protocol (MCP) server that gives code agents direct access to i18n scanning and translation tools.

Setup

Before configuring the MCP server, make sure you have:

1. Installed glotctl as a dev dependency (see Quick Start)
2. Initialized the configuration with glot init

Adjust the command based on your package manager:

Package Manager	Command
npm	["npx", "glot", "serve"]
pnpm	["pnpm", "exec", "glot", "serve"]
yarn	["yarn", "glot", "serve"]
bun	["bunx", "glot", "serve"]

The examples below use npm. Replace the command with the appropriate one for your package manager.

Claude Code

Option 1: Using CLI (recommended)

claude mcp add --transport stdio glot -- npx glot serve

Option 2: Using project configuration

Create .mcp.json in your project root to share with your team:

{
  "mcpServers": {
    "glot": {
      "command": "npx",
      "args": ["glot", "serve"]
    }
  }
}

Cursor

Add glot to your Cursor MCP configuration. Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global access):

{
  "mcpServers": {
    "glot": {
      "command": "npx",
      "args": ["glot", "serve"]
    }
  }
}

OpenCode

Configure glot in your project’s opencode.json file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "glot": {
      "type": "local",
      "command": ["npx", "glot", "serve"],
      "enabled": true
    }
  }
}

Other MCP-Compatible Agents

For other agents that support MCP, run the glot server with:

npx glot serve

The server communicates over stdio using the MCP protocol.

Available Tools

The MCP server provides 9 tools. All tools require the project_root_path parameter.

get_config

Returns the current glot configuration.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory

Output:

{
  "fromFile": true,
  "config": {
    "primaryLocale": "en",
    "messagesDir": "./messages",
    "includes": ["src/app/[locale]", "src/components"],
    "ignores": [],
    "ignoreTestFiles": true,
    "ignoreTexts": [],
    "checkedAttributes": ["placeholder", "title", "alt", "aria-label"]
  }
}

get_locales

Lists available locale files with key counts.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory

Output:

{
  "messagesDir": "./messages",
  "primaryLocale": "en",
  "locales": [
    { "locale": "en", "filePath": "./messages/en.json", "keyCount": 156 },
    { "locale": "es", "filePath": "./messages/es.json", "keyCount": 152 }
  ]
}

scan_overview

Returns statistics of all i18n issues in the project. Use this first to understand the overall state.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory

Output:

{
  "hardcoded": {
    "totalCount": 12,
    "fileCount": 5
  },
  "primaryMissing": {
    "totalCount": 4
  },
  "replicaLag": {
    "totalCount": 8,
    "affectedLocales": ["es", "fr"]
  },
  "untranslated": {
    "totalCount": 3,
    "affectedLocales": ["es", "fr"]
  },
  "typeMismatch": {
    "totalCount": 1,
    "affectedLocales": ["es"]
  }
}

scan_hardcoded

Returns detailed hardcoded text issues with pagination support.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory
limit	number	No	Results per page (default: 20, max: 100)
offset	number	No	Offset for pagination (default: 0)

Output:

{
  "totalCount": 12,
  "totalFileCount": 5,
  "items": [
    {
      "filePath": "./src/components/Button.tsx",
      "line": 5,
      "col": 22,
      "text": "Submit",
      "sourceLine": "    return <button>Submit</button>;"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "hasMore": false
  }
}

scan_primary_missing

Lists translation keys used in code but missing from the primary locale file.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory
limit	number	No	Results per page (default: 50, max: 100)
offset	number	No	Offset for pagination (default: 0)

Output:

{
  "totalCount": 4,
  "items": [
    {
      "key": "common.submit",
      "filePath": "./src/components/Button.tsx",
      "line": 15
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "hasMore": false
  }
}

scan_replica_lag

Lists keys that exist in the primary locale but are missing from other locales. Includes code usage locations to help prioritize fixes.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory
limit	number	No	Results per page (default: 50, max: 100)
offset	number	No	Offset for pagination (default: 0)

Output:

{
  "totalCount": 8,
  "items": [
    {
      "key": "common.newFeature",
      "value": "New Feature",
      "filePath": "./messages/en.json",
      "line": 15,
      "existsIn": "en",
      "missingIn": ["es", "fr"],
      "usages": [
        { "filePath": "./src/components/Feature.tsx", "line": 25, "col": 10 }
      ],
      "totalUsages": 3
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "hasMore": false
  }
}

The usages array contains up to 3 code locations where the key is used. totalUsages shows the total count (may exceed 3).

scan_untranslated

Lists translation values that are identical to the primary locale or are empty strings, which may indicate they haven’t been translated yet. Includes code usage locations.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory
limit	number	No	Results per page (default: 50, max: 100)
offset	number	No	Offset for pagination (default: 0)

Output:

{
  "totalCount": 3,
  "items": [
    {
      "key": "common.submit",
      "value": "Submit",
      "filePath": "./messages/en.json",
      "line": 5,
      "primaryLocale": "en",
      "identicalIn": ["es", "fr"],
      "emptyIn": ["ko"],
      "usages": [
        { "filePath": "./src/components/Button.tsx", "line": 12, "col": 8 }
      ],
      "totalUsages": 5
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "hasMore": false
  }
}

The identicalIn array lists locales where the value is identical to the primary locale. The emptyIn array lists locales where the value is an empty string. The usages array contains up to 3 code locations where the key is used.

scan_type_mismatch

Lists keys whose value type differs between the primary locale and other locales. These should be fixed first because they can cause runtime crashes.

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory
limit	number	No	Results per page (default: 50, max: 100)
offset	number	No	Offset for pagination (default: 0)

Output:

{
  "totalCount": 1,
  "items": [
    {
      "key": "common.items",
      "expectedType": "array",
      "primaryFilePath": "./messages/en.json",
      "primaryLine": 12,
      "primaryLocale": "en",
      "mismatchedIn": [
        {
          "locale": "es",
          "actualType": "string",
          "filePath": "./messages/es.json",
          "line": 8
        }
      ],
      "usages": [
        { "filePath": "./src/components/List.tsx", "line": 18, "col": 9 }
      ],
      "totalUsages": 2
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "hasMore": false
  }
}

add_translations

Adds new translation keys to one or more locale files. Supports nested keys (e.g., common.buttons.submit).

Input:

Parameter	Type	Required	Description
project_root_path	string	Yes	Path to the project root directory
translations	array	Yes	Array of translation entries

Each translation entry:

Field	Type	Description
locale	string	Locale code (e.g., “en”, “zh-CN”)
keys	object	Key-value pairs to add

Example Input:

{
  "project_root_path": "/path/to/project",
  "translations": [
    {
      "locale": "en",
      "keys": {
        "common.submit": "Submit",
        "common.cancel": "Cancel"
      }
    },
    {
      "locale": "es",
      "keys": {
        "common.submit": "Enviar",
        "common.cancel": "Cancelar"
      }
    }
  ]
}

Output:

{
  "success": true,
  "results": [
    {
      "locale": "en",
      "success": true,
      "filePath": "./messages/en.json",
      "addedCount": 2,
      "updatedCount": 0
    }
  ],
  "summary": {
    "totalLocales": 2,
    "successfulLocales": 2,
    "failedLocales": 0,
    "totalKeysAdded": 4,
    "totalKeysUpdated": 0
  }
}

Recommended Workflow

The MCP server instructions guide code agents to follow this workflow:

1. scan_overview      → Understand the overall state
2. Fix type_mismatch → Resolve type mismatches first
3. Fix hardcoded     → Replace text with t() calls, add keys
4. Fix primary_missing → Add missing keys to primary locale
5. Fix replica_lag    → Sync keys to other locales

This order is important! Fixing hardcoded issues may create new primary_missing issues, and fixing those may create new replica_lag issues.

Related

Agent Skill

Install the glot-i18n skill for guided workflows

Configuration

Configure glot for your project