Texterify

npm version License: ISC

A Model Context Protocol (MCP) server that gives LLM agents full access to the Texterify translation management API. Search, create, update, and delete translation keys and their translations without leaving your editor.

Why

Managing translations during development means constant context-switching between your code editor and the Texterify web UI. This MCP server eliminates that friction -- your AI coding assistant can look up keys, add translations, find untranslated strings, and manage languages directly through natural language.

Quick Start

The fastest way to get started is via npx:

npx texterify-mcp

Or install globally:

npm install -g texterify-mcp

The server requires the following environment variables:

Variable	Required	Description
TEXTERIFY_AUTH_EMAIL	Yes	Your Texterify account email
TEXTERIFY_AUTH_SECRET	Yes	Your Texterify API secret / access token
TEXTERIFY_PROJECT_ID	No	UUID of the project to operate on (can be provided per-tool or via env)
TEXTERIFY_API_BASE_URL	No	API base URL (default: https://app.texterify.com/api)
TEXTERIFY_API_VERSION	No	API version (default: v1)

You can find your API credentials in your Texterify account settings.

Note on TEXTERIFY_PROJECT_ID: While this can be set as an environment variable for convenience, every project-scoped tool also accepts an optional project_id parameter. The resolution order is: tool parameter → environment variable → error. You can find your project ID in your project's texterify.json file or by using the list_projects tool.

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "texterify": {
      "command": "npx",
      "args": ["-y", "texterify-mcp"],
      "env": {
        "TEXTERIFY_AUTH_EMAIL": "[email protected]",
        "TEXTERIFY_AUTH_SECRET": "your-api-secret",
        "TEXTERIFY_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %AppData%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code

claude mcp add --transport stdio \
  --env [email protected] \
  --env TEXTERIFY_AUTH_SECRET=your-api-secret \
  --env TEXTERIFY_PROJECT_ID=your-project-uuid \
  texterify -- npx -y texterify-mcp

Note: All flags (--transport, --env) must come before the server name. The -- separates the server name from the command. TEXTERIFY_PROJECT_ID is optional and can be provided per-tool.

OpenCode

Add to your opencode.json (or opencode.jsonc):

{
  "mcp": {
    "texterify": {
      "type": "local",
      "command": ["npx", "-y", "texterify-mcp"],
      "environment": {
        "TEXTERIFY_AUTH_EMAIL": "[email protected]",
        "TEXTERIFY_AUTH_SECRET": "your-api-secret",
        "TEXTERIFY_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

TEXTERIFY_PROJECT_ID is optional and can be provided per-tool.

VS Code / Copilot

Add to .vscode/mcp.json in your workspace (or add to your user profile via MCP: Add Server in the Command Palette):

{
  "servers": {
    "texterify": {
      "command": "npx",
      "args": ["-y", "texterify-mcp"],
      "env": {
        "TEXTERIFY_AUTH_EMAIL": "[email protected]",
        "TEXTERIFY_AUTH_SECRET": "your-api-secret",
        "TEXTERIFY_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

TEXTERIFY_PROJECT_ID is optional and can be provided per-tool.

Cursor

Add to .cursor/mcp.json in your project root (project-specific) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "texterify": {
      "command": "npx",
      "args": ["-y", "texterify-mcp"],
      "env": {
        "TEXTERIFY_AUTH_EMAIL": "[email protected]",
        "TEXTERIFY_AUTH_SECRET": "your-api-secret",
        "TEXTERIFY_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

TEXTERIFY_PROJECT_ID is optional and can be provided per-tool.

Available Tools

list_keys

Search and list translation keys with pagination. Supports filtering by name and untranslated status.

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
search	string	No	Filter keys by name
only_untranslated	boolean	No	Return only untranslated keys
page	number	No	Page number (default: 1)
per_page	number	No	Results per page (default: 10, max: 50)

get_key

Retrieve a single translation key with all its translations.

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
key_id	string	Yes	UUID of the key

create_key

Create a new translation key.

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
name	string	Yes	Key name (e.g. welcome_message)
description	string	No	Human-readable description
html_enabled	boolean	No	Allow HTML in value
pluralization_enabled	boolean	No	Enable pluralization

update_key

Update an existing key's properties. Only provided fields are changed.

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
key_id	string	Yes	UUID of the key
name	string	No	New key name
description	string	No	New description
html_enabled	boolean	No	Toggle HTML support
pluralization_enabled	boolean	No	Toggle pluralization

delete_keys

Delete one or more translation keys.

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
key_ids	string[]	Yes	Array of key UUIDs to delete

set_translation

Create or update a translation for a specific key and language (upsert).

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
key_id	string	Yes	UUID of the key
language_id	string	Yes	UUID of the language
content	string	Yes	Translation text
zero	string	No	Plural form: zero
one	string	No	Plural form: one
two	string	No	Plural form: two
few	string	No	Plural form: few
many	string	No	Plural form: many

list_languages

List languages configured in the project with translation progress.

Parameter	Type	Required	Description
project_id	string	No	The Texterify project UUID. If omitted, uses TEXTERIFY_PROJECT_ID env var
search	string	No	Filter by language name
page	number	No	Page number (default: 1)
per_page	number	No	Results per page (default: 10, max: 50)

list_projects

List all Texterify projects accessible to the authenticated user. Useful for finding project IDs.

Parameter	Type	Required	Description
search	string	No	Filter by project name
page	number	No	Page number (default: 1)
per_page	number	No	Results per page (default: 10, max: 50)

Example Prompts

Once configured, you can ask your AI assistant things like:

• "List all untranslated keys in my project"
• "Create a key called checkout.success_message with description 'Shown after payment'"
• "What languages are configured in this project?"
• "Set the German translation for key X to 'Willkommen'"
• "Find all keys matching 'error'"
• "Delete the keys I just created"

Development

Requires Node.js 18+ and pnpm.

# Install dependencies
pnpm install

# Run the server
pnpm start

# Run in watch mode
pnpm dev

# Type-check
pnpm exec tsc --noEmit

# Run tests
pnpm test

How It Works

The server uses stdio transport -- it communicates over stdin/stdout using the MCP JSON-RPC protocol. All logging goes to stderr to keep the protocol channel clean.

MCP Client (LLM Agent)
    |  stdio (JSON-RPC)
    v
Tool Handlers (Zod-validated inputs)
    |
    v
API Client (native fetch)
    |
    v
Texterify REST API

• No build step -- TypeScript is executed directly via tsx
• Native fetch -- zero HTTP library dependencies (Node.js 18+)
• Zod v4 schemas for input validation and automatic JSON Schema generation
• Structured error handling with clear messages for auth failures, missing resources, and validation errors

License

ISC