Coding Agents

Connect coding agents like Cursor, Claude Code, Windsurf, Zed, Codex, and Antigravity to your translation workspace.

Two ways to connect. Agents that support remote MCP (Claude Code, Cursor) can use the hosted server at https://mcp.better-i18n.com/mcp and sign in via OAuth — no API key needed. Agents that only run local stdio servers use the npx bridge with an API key. Both are shown per-agent below.

For ChatGPT, Claude (web), or Gemini, use the AI Assistants guide instead — no installation required.

Get your API Key

Sign in to dash.better-i18n.com.
Go to Settings > API Keys.
Create a new key and copy it.

Configure Project Context

The MCP server needs to know which project to manage. It reads the projectId field from your i18n.config.ts.

i18n.config.ts

import { createI18n } from "@better-i18n/next";

export const i18n = createI18n({
  projectId: "your-org/your-project", // MCP uses this ID
  defaultLocale: "en",
});

Configure your AI Assistant

Pass your API key using the BETTER_I18N_API_KEY environment variable.

Recommended — OAuth, no API key. Add the remote server in Settings → MCP → Add new MCP server, choose Remote, and paste:

https://mcp.better-i18n.com/mcp

Cursor opens your browser to sign in on first use — no key to manage.

Alternative — API key (~/.cursor/mcp.json):

~/.cursor/mcp.json

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

Recommended — OAuth, no API key. Add the remote server and sign in through your browser:

Terminal

claude mcp add --transport http --scope user better-i18n https://mcp.better-i18n.com/mcp

Then run /mcp inside Claude Code, pick better-i18n → Authenticate, and approve in your browser. No key to copy or rotate — the token refreshes automatically.

Alternative — API key (for offline / self-hosted setups):

Terminal

claude mcp add better-i18n -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest

Claude Code automatically manages the .mcp.json configuration. View and manage servers with claude mcp list.

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

Add this to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

Add this to your Zed settings (~/.config/zed/settings.json):

~/.config/zed/settings.json

{
  "context_servers": {
    "better-i18n": {
      "command": {
        "path": "npx",
        "args": ["-y", "@better-i18n/mcp@latest"],
        "env": {
          "BETTER_I18N_API_KEY": "your-api-key"
        }
      },
      "settings": {}
    }
  }
}

Option 1: CLI command

Terminal

codex mcp add better-i18n --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest

Option 2: Manual config (~/.codex/config.toml)

~/.codex/config.toml

[mcp_servers.better-i18n]
command = "npx"
args = ["-y", "@better-i18n/mcp@latest"]

[mcp_servers.better-i18n.env]
BETTER_I18N_API_KEY = "your-api-key"

Add this to your GEMINI.md or .rules file:

GEMINI.md

MCP Servers:
- better-i18n: @better-i18n/mcp@latest (stdio)

Environment Variables:
BETTER_I18N_API_KEY: your-api-key

Verify Connectivity

Ask your AI assistant a translation-related question to verify the setup:

"Show me the translation status for my current project."

If configured correctly, the AI will use the getProject tool to fetch your real-time stats.

Content Management MCP

If you also use Better i18n's headless CMS features, add the content MCP server separately:

~/.cursor/mcp.json

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    },
    "better-i18n-content": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp-content@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

Run both commands in your terminal:

Terminal

claude mcp add better-i18n -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest
claude mcp add better-i18n-content -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp-content@latest

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    },
    "better-i18n-content": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp-content@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    },
    "better-i18n-content": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp-content@latest"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    }
  }
}

~/.config/zed/settings.json

{
  "context_servers": {
    "better-i18n": {
      "command": {
        "path": "npx",
        "args": ["-y", "@better-i18n/mcp@latest"],
        "env": {
          "BETTER_I18N_API_KEY": "your-api-key"
        }
      },
      "settings": {}
    },
    "better-i18n-content": {
      "command": {
        "path": "npx",
        "args": ["-y", "@better-i18n/mcp-content@latest"],
        "env": {
          "BETTER_I18N_API_KEY": "your-api-key"
        }
      },
      "settings": {}
    }
  }
}

Option 1: CLI commands

Terminal

codex mcp add better-i18n --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp@latest
codex mcp add better-i18n-content --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp-content@latest

Option 2: Manual config (~/.codex/config.toml)

~/.codex/config.toml

[mcp_servers.better-i18n]
command = "npx"
args = ["-y", "@better-i18n/mcp@latest"]

[mcp_servers.better-i18n.env]
BETTER_I18N_API_KEY = "your-api-key"

[mcp_servers.better-i18n-content]
command = "npx"
args = ["-y", "@better-i18n/mcp-content@latest"]

[mcp_servers.better-i18n-content.env]
BETTER_I18N_API_KEY = "your-api-key"

GEMINI.md

MCP Servers:
- better-i18n: @better-i18n/mcp@latest (stdio)
- better-i18n-content: @better-i18n/mcp-content@latest (stdio)

Environment Variables:
BETTER_I18N_API_KEY: your-api-key

The translation and content MCP servers are separate packages to keep each focused. You can install one or both depending on your needs.

Environment Variables

Variable	Required	Description
`BETTER_I18N_API_KEY`	Yes	Your organization API key
`BETTER_I18N_API_URL`	No	Custom API URL (default: dash.better-i18n.com)
`BETTER_I18N_DEBUG`	No	Enable detailed debug logging

Get your API Key

Configure Project Context

Configure your AI Assistant

Verify Connectivity

Content Management MCP

Environment Variables

On this page