i18n-tools-mcp

# @trivle/i18n-tools-mcp

MCP server for querying and managing JSON translation files. Designed for AI agents (Claude Code, Cursor, etc.) to read and write i18n, i18next, react-i18next, and next-i18next translations directly through the Model Context Protocol.

Supports flat (`{locale}.json`) and namespaced (`{locale}/{namespace}.json`) directory layouts with dot-notation keys.

## Install

Ask your AI agent:

> Install the @trivle/i18n-tools-mcp MCP server. The translations directory is at ./messages and the base locale is nl.

Or add it manually to your MCP client config (e.g. `.cursor/settings.json`):

```json
{
  "mcpServers": {
    "i18n-tools": {
      "command": "npx",
      "args": ["@trivle/i18n-tools-mcp", "./messages", "nl"]
    }
  }
}
```

Arguments:

1. **Required**: Path to the directory containing your translation files
2. **Optional**: Base locale code (default: `nl`) — used in tool descriptions to guide AI agents
3. **Optional**: JSON indentation spaces (default: `4`)

## Directory structures

Both flat and namespaced layouts are auto-detected.

**Flat** — one JSON file per locale:

```
messages/
  en.json
  nl.json
```

**Namespaced** — subdirectory per locale, one JSON file per namespace (i18next-style):

```
messages/
  en/
    common.json
    auth.json
  nl/
    common.json
    auth.json
```

In namespace mode, prefix keys with the namespace: `common:Users.name`. Read operations (`query`, `list`, `search`, `missing`) work across all namespaces when no prefix is given. Write operations (`set`, `add`) require a namespace prefix.

## Tools

### `query`

Look up a translation key across all locale files. Returns the value for each locale that has the key.

| Parameter | Type   | Required | Description                              |
|-----------|--------|----------|------------------------------------------|
| `key`     | string | yes      | Dot-notation key, e.g. `"Users.name"` or `"common:Users.name"` |

### `set`

Set a translation value for a si