Movabase MCP

Movabase exposes a remote MCP server for translation workflows at https://app.movabase.com/api/mcp.

It is built for AI clients that need to inspect a project, translate content, find missing values, and write translations back into Movabase without going through the REST API one endpoint at a time.

What it gives you

• Project-scoped access to translations through an API key
• Read tools for languages, files, keys, current values, and missing values
• Write tools for single updates, bulk imports, key deletion, and language creation
• AI translation helpers for single strings and batches of missing keys
• A standard MCP HTTP transport that works with remote MCP clients

How it works

The MCP server lives in the web app and is exposed through /api/mcp.

Each request:

1. Sends Authorization: Bearer <MOVABASE_API_KEY>
2. Verifies the key with Unkey
3. Extracts the projectId stored in the key metadata
4. Scopes every MCP tool call to that project
5. Executes the requested read or write operation against Movabase translation data

Movabase currently supports GET, POST, and DELETE requests on the MCP endpoint and uses the standard streamable HTTP server transport from the MCP SDK.

Authentication

Create a project API key first from the project settings UI or with the project key endpoints.

Use it as a bearer token:

Authorization: Bearer loko_YOUR_API_KEY

Important details:

• Keys are project-scoped
• Keys are shown only once when created
• If a key has no projectId metadata, MCP access is rejected

Limits

The MCP route currently applies these server-side limits per API key:

• 60 requests per minute
• 1000 requests per day
• Standard request body validation from Movabase

Relevant input limits in translation workflows:

• Translation key: 256 characters
• Translation value: 8192 characters
• File name: 256 characters
• API key name: 128 characters
• Request body: 4 MiB

Endpoint and client configuration

Most MCP clients that support remote HTTP servers can point directly at Movabase:

{
  "mcpServers": {
    "movabase": {
      "type": "http",
      "url": "https://app.movabase.com/api/mcp",
      "headers": {
        "Authorization": "Bearer loko_YOUR_API_KEY"
      }
    }
  }
}

Client config shapes vary a little by host, but the important pieces are always the same:

• server URL: https://app.movabase.com/api/mcp
• transport: remote HTTP MCP
• auth header: Authorization: Bearer <key>

Install in AI tools

The Movabase MCP is a remote HTTP MCP server. Any AI tool that supports remote MCP servers can connect to it with the same three values:

• name: movabase
• url: https://app.movabase.com/api/mcp
• header: Authorization: Bearer loko_YOUR_API_KEY

Cursor

In Cursor, users should do two things:

1. connect the Movabase MCP
2. add the Movabase translation rule file to their own project

For the MCP connection, open the MCP servers/settings screen and add a new server using the remote HTTP option.

Use this config:

{
  "mcpServers": {
    "movabase": {
      "type": "http",
      "url": "https://app.movabase.com/api/mcp",
      "headers": {
        "Authorization": "Bearer loko_YOUR_API_KEY"
      }
    }
  }
}

After saving the server:

1. reload Cursor if it does not connect automatically
2. confirm the movabase server appears in the MCP tools list
3. ask Cursor to call list_languages or list_files as a smoke test

For the instruction file, download:

• Cursor rule file

Then place it in the user's own repository at:

.cursor/rules/movabase-mcp-translations.mdc

Cursor rules use .mdc files under .cursor/rules/, so this is the correct native format for external users using Cursor. Cursor Rules docs

Claude Code

In Claude Code, users should also do two things:

1. connect the Movabase MCP
2. add the Movabase translation instructions to their own Claude project memory

Claude Code supports remote HTTP MCP servers directly, so users can install the server from the terminal:

claude mcp add --transport http movabase https://app.movabase.com/api/mcp \
  --header "Authorization: Bearer loko_YOUR_API_KEY"

Or they can configure the same server with JSON.

Use the same server entry:

{
  "mcpServers": {
    "movabase": {
      "type": "http",
      "url": "https://app.movabase.com/api/mcp",
      "headers": {
        "Authorization": "Bearer loko_YOUR_API_KEY"
      }
    }
  }
}

Then restart Claude Code or reload MCP servers and verify it can see the movabase tools. Claude Code documents both remote HTTP MCP setup and project memory via CLAUDE.md. Claude Code MCP docs Claude Code memory docs

Good first checks:

• list_languages
• list_files
• search_translations

For the instruction file, download:

• Claude instruction file

Then use one of these install options in the user's own project:

Option A: append the file contents into CLAUDE.md at the repo root
Option B: save it as .claude/rules/movabase-mcp-translations.md

Other AI tools

For any other MCP-compatible tool:

1. create a new remote MCP server
2. set the URL to https://app.movabase.com/api/mcp
3. send Authorization: Bearer loko_YOUR_API_KEY
4. save and reconnect the tool

If the tool only supports local stdio MCP servers and does not support remote HTTP MCP yet, it will need a small bridge or proxy in front of Movabase.

Recommended first prompt after install

Once the MCP is connected, a good verification prompt is:

Use the movabase MCP to list the languages and files in my project, then explain the translation structure before making any changes.

Tool catalog

Recommended implementation flow

If you are building an AI workflow on top of the Movabase MCP, this order works well:

1. list_languages
2. list_files
3. search_translations or list_keys before creating anything new
4. get_translations when you need existing copy for terminology or placeholder checks
5. upsert_translation for one-off changes or bulk_upsert_translations for batches
6. translate_missing when the goal is to fill empty values in a target language

That sequence keeps the AI grounded in the real project state before it writes.

When to use MCP instead of the REST API

Use the Movabase MCP when the caller is an AI agent that needs to reason about the project while it works.

MCP is the better fit when the agent needs to:

• Inspect available languages and files before acting
• Search existing keys before inventing new ones
• Find missing translations and fill them in one workflow
• Translate and save content inside the same tool session

The REST API is still a good fit for deterministic scripts, exports, and CI jobs that already know the exact endpoints they need.

Translation workflow guidance

For translation-writing agents, the safest pattern is:

1. Inspect the project first
2. Reuse existing keys and terminology where possible
3. Preserve placeholders, interpolation tokens, HTML tags, markdown, and product names
4. Prefer writing through the Movabase MCP instead of generating free-form translations outside project context

Why the MCP should be preferred for new translations:

• It knows the real project languages and files
• It can look up existing wording before translating
• It can detect missing values instead of guessing
• It writes directly into Movabase, which avoids copy-paste drift

Important behavior notes

• delete_translation_key is a soft delete, not a hard delete
• translate_missing processes up to 20 keys by default unless limit is provided
• search_translations can be used with an empty query and onlyEmpty: true to find empty entries
• The remote MCP is translation-focused; it does not expose the richer project-context helper used by the in-app assistant, so external agents should call list_languages and list_files early

Language-based projects

Some Movabase projects effectively behave as one file per language. External MCP clients should avoid inventing new file names in those projects.

A good rule is:

• call list_files first
• reuse existing file names for the target language
• if the structure looks like one locale file per language, keep following that pattern

External AI instruction pack

This repository contains three related assets:

.agents/skills/movabase-mcp-translations/SKILL.md
apps/docs/public/downloads/cursor/movabase-mcp-translations.mdc
apps/docs/public/downloads/claude/movabase-mcp-translations.md

Use them like this:

• SKILL.md is the Trae-style source version used in this repository
• the Cursor .mdc file is what external Cursor users should install
• the Claude markdown file is what external Claude Code users should add to CLAUDE.md or .claude/rules/

The MCP and the instruction files are separate:

• the MCP gives the AI real Movabase tools
• the instruction file tells the AI when and how to use those tools well

Example use cases

Fill all missing German translations

• list_languages
• list_files
• translate_missing with targetLanguage: "de" and targetLanguageName: "German"

Add a new locale and import translations

• add_language
• bulk_upsert_translations

Translate one new key safely

• search_translations for similar wording
• translate_text
• upsert_translation

Developer takeaway

The Movabase MCP is the translation-aware interface for AI clients. If the caller needs project context, existing terminology, missing-value discovery, or direct write-back into Movabase, use the MCP first and treat the REST API as the lower-level alternative.