---
title: Coding Agents
description: Configure MCP server for Cursor, Claude Code, Windsurf, Zed, Codex, and more
icon: Rocket
---

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.

<Callout type="info">
  For **ChatGPT**, **Claude** (web), or **Gemini**, use the [AI Assistants](/mcp/ai-assistants) guide instead — no installation required.
</Callout>

<Steps>

<Step>
### Get your API Key

1. Sign in to [dash.better-i18n.com](https://dash.better-i18n.com).
2. Go to **Settings > API Keys**.
3. Create a new key and copy it.
</Step>

<Step>
### Configure Project Context

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

```ts title="i18n.config.ts"
import { createI18n } from "@better-i18n/next";

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

</Step>

<Step>
### Configure your AI Assistant

Pass your API key using the `BETTER_I18N_API_KEY` environment variable.

<Tabs items={['Cursor', 'Claude Code', 'Claude Desktop', 'Windsurf', 'Zed', 'Codex', 'Antigravity']}>
  <Tab value="Cursor">
    Add this to your MCP settings in Cursor (`~/.cursor/mcp.json`):
    ```json title="~/.cursor/mcp.json"
    {
      "mcpServers": {
        "better-i18n": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab value="Claude Code">
    Run this command in your terminal:
    ```bash title="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. You can view and manage servers with `claude mcp list`.
  </Tab>
  <Tab value="Claude Desktop">
    Add this to your Claude Desktop config:
    ```json
    {
      "mcpServers": {
        "better-i18n": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab value="Windsurf">
    Add this to your Windsurf MCP config (`~/.codeium/windsurf/mcp_config.json`):
    ```json title="~/.codeium/windsurf/mcp_config.json"
    {
      "mcpServers": {
        "better-i18n": {
          "command": "npx",
          "args": ["-y", "@better-i18n/mcp@latest"],
          "env": {
            "BETTER_I18N_API_KEY": "your-api-key"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab value="Zed">
    Add this to your Zed settings (`~/.config/zed/settings.json`):
    ```json title="~/.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": {}
        }
      }
    }
    ```
  </Tab>
  <Tab value="Codex">
    **Option 1: CLI command**
    ```bash title="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`)
    ```toml title="~/.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"
    ```
  </Tab>
  <Tab value="Antigravity">
    Add this to your `GEMINI.md` or `.rules` file:
    ```markdown title="GEMINI.md"
    MCP Servers:
    - better-i18n: @better-i18n/mcp@latest (stdio)

    Environment Variables:
    BETTER_I18N_API_KEY: your-api-key
    ```
  </Tab>
</Tabs>
</Step>

<Step>
### 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.

</Step>

</Steps>

## Content Management MCP

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

<Tabs items={['Cursor', 'Claude Code', 'Claude Desktop', 'Windsurf', 'Zed', 'Codex', 'Antigravity']}>
  <Tab value="Cursor">
    ```json title="~/.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"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab value="Claude Code">
    Run both commands in your terminal:
    ```bash title="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
    ```
  </Tab>
  <Tab value="Claude Desktop">
    ```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"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab value="Windsurf">
    ```json title="~/.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"
          }
        }
      }
    }
    ```
  </Tab>
  <Tab value="Zed">
    ```json title="~/.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": {}
        }
      }
    }
    ```
  </Tab>
  <Tab value="Codex">
    **Option 1: CLI commands**
    ```bash title="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`)
    ```toml title="~/.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"
    ```
  </Tab>
  <Tab value="Antigravity">
    ```markdown title="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
    ```
  </Tab>
</Tabs>

<Callout type="info">
  The translation and content MCP servers are separate packages to keep each focused. You can install one or both depending on your needs.
</Callout>

## 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                  |
