> ## Documentation Index
> Fetch the complete documentation index at: https://glotctl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Configure glot as an MCP server for code agents

Glot provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives code agents direct access to i18n scanning and translation tools.

## Setup

<Note>
  Before configuring the MCP server, make sure you have:

  1. Installed glotctl as a dev dependency (see [Quick Start](/quickstart#installation))
  2. Initialized the configuration with `glot init`
</Note>

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)**

```bash theme={null}
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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "mcpServers": {
    "glot": {
      "command": "npx",
      "args": ["glot", "serve"]
    }
  }
}
```

### OpenCode

Configure glot in your project's `opencode.json` file:

```json theme={null}
{
  "$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:

```bash theme={null}
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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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
```

<Note>
  This order is important! Fixing hardcoded issues may create new primary\_missing issues, and fixing those may create new replica\_lag issues.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Agent Skill" icon="brain" href="/agents/skill">
    Install the glot-i18n skill for guided workflows
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Configure glot for your project
  </Card>
</CardGroup>