Coding Agents

Set up the local MCP server for coding agents like Cursor, Claude Code, Windsurf, Zed, Codex, and Antigravity. This runs a local process via npx and authenticates with an API key.

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 looks for a project identifier in your i18n.config.ts.

i18n.config.ts

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

export const i18n = createI18n({
  project: "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.

Add this to your MCP settings in Cursor (~/.cursor/mcp.json):

~/.cursor/mcp.json

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

Run this command in your terminal:

Terminal

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

Claude Code automatically manages the .mcp.json configuration. You can view and manage servers with claude mcp list.

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["@better-i18n/mcp"],
      "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": ["@better-i18n/mcp"],
      "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": ["@better-i18n/mcp"],
        "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

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

~/.codex/config.toml

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

[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 (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": ["@better-i18n/mcp"],
      "env": {
        "BETTER_I18N_API_KEY": "your-api-key"
      }
    },
    "better-i18n-content": {
      "command": "npx",
      "args": ["@better-i18n/mcp-content"],
      "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
claude mcp add better-i18n-content -s user -e BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp-content

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

~/.codeium/windsurf/mcp_config.json

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

~/.config/zed/settings.json

{
  "context_servers": {
    "better-i18n": {
      "command": {
        "path": "npx",
        "args": ["@better-i18n/mcp"],
        "env": {
          "BETTER_I18N_API_KEY": "your-api-key"
        }
      },
      "settings": {}
    },
    "better-i18n-content": {
      "command": {
        "path": "npx",
        "args": ["@better-i18n/mcp-content"],
        "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
codex mcp add better-i18n-content --env BETTER_I18N_API_KEY=your-api-key -- npx -y @better-i18n/mcp-content

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

~/.codex/config.toml

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

[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"]

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

GEMINI.md

MCP Servers:
- better-i18n: @better-i18n/mcp (stdio)
- better-i18n-content: @better-i18n/mcp-content (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