Ship translations with confidence.

Setup

1. Sign in to GoLocalise and open Settings → Developer → API credentials.
2. Create a dedicated credential. The default selection (projects:read, translations:read, exports:read) is read-only. Add imports:write only when the agent must import translations.
3. Copy the access key and the one-time secret from the dialog. The same dialog shows a ready-to-use MCP configuration with both values filled in.
4. Add the configuration below to your MCP host and restart it.
5. Ask the assistant to list your GoLocalise projects.

{
  "mcpServers": {
    "golocalise": {
      "command": "npx",
      "args": ["-y", "@golocalise/mcp-server"],
      "env": {
        "GOLOCALISE_ACCESS_KEY": "gl_live_…",
        "GOLOCALISE_SECRET": "gl_secret_…"
      }
    }
  }
}

Host configuration

• Cursor~/.cursor/mcp.json

  Add the block to the global file for every project, to .cursor/mcp.json inside one workspace, or use Settings → MCP → Add new MCP server.

• Claude Desktopclaude_desktop_config.json

  Open Settings → Developer → Edit Config and add the block to the config file.

• Claude Code.mcp.json

  Add the block to the .mcp.json file in your project root, or register the same command, arguments, and environment values with claude mcp add.

The JSON shape is identical everywhere: command runs npx, which downloads and executes the published package and passes the credential through env.

Configuration reference

Malformed or non-http(s) origins and missing credential variables make the server exit immediately with a clear error instead of failing later mid-tool.

{
  "mcpServers": {
    "golocalise": {
      "command": "npx",
      "args": ["-y", "@golocalise/mcp-server"],
      "env": {
        "GOLOCALISE_ACCESS_KEY": "gl_live_…",
        "GOLOCALISE_SECRET": "gl_secret_…",
        "GOLOCALISE_API_ORIGIN": "https://api.golocalise.me"
      }
    }
  }
}

Credentials and scopes

Use read-only scopes for research and review agents. Grant imports:write only to an agent you trust to import translations. Credentials are server-side secrets: keep them in the host's private environment configuration, never commit them, never paste them into prompts, and rotate or revoke them from Organization Settings. Secrets are displayed only once at creation or rotation; the dashboard never reveals a stored secret again.

Tools

Responses are bounded; if a response is too large the server explains how to narrow languages, namespaces, keys, statuses, or item classification.

Analyze, approve, and apply

1. Step 1

   Analyze

   golocalise_analyze_import Uploads up to 20 files (inline UTF-8 content or contentBase64 for binary formats such as XLSX) and returns a durable session. Nothing is written.

2. Step 2

   Review

   golocalise_get_import_session Poll until the session is ready, read the report and counts, then page golocalise_list_import_items?classification=conflict to collect every decision the review policy requires.

3. Step 3

   Apply

   golocalise_proceed_import Call with the session's analysisHash and projectStateHash exactly as returned, plus one resolution (keep_existing, use_imported, or exclude) per review-policy conflict. The server rejects stale or partial snapshots.

4. Step 4

   Wait

   Poll the session until it reports completed or failed.

Production imports stay disabled and must go through the dashboard promotion flow. Development and staging accept imports. Cancelling or abandoning a session never deletes translations committed by another completed session.

Troubleshooting

• The host reports the credential variables are required

  The env block is missing or malformed. Fix the JSON and fully restart the host.

• GoLocalise API 401

  The secret is wrong, expired, rotated, or revoked. Rotate the credential and update the host configuration.

• GoLocalise API 403

  The credential lacks the scope for that tool. Add only the scope you actually need.

• GoLocalise API 404

  Wrong project or environment ID, an archived project, or a project that belongs to another organization. Credentials only ever see their own organization.

• GoLocalise API 429

  The per-credential request budget was exceeded. Wait a minute or narrow the requests.

• Response above the MCP limit

  Add filters (languages, namespaces, keys, statuses) or page through sessions with limit/cursor.

• npx fails or the server exits immediately

  Confirm Node.js 20.19+ is on PATH, then try npx -y @golocalise/mcp-server once from a terminal with the same environment variables to see the exact startup error.