@translateimage/mcp-server

MCP (Model Context Protocol) server for TranslateImage - AI-powered image translation.

Overview

This package provides a Model Context Protocol server that exposes TranslateImage translation capabilities to Claude and other MCP-compatible clients. It enables AI assistants to TranslateImage:

• Translate text in images while preserving layout
• Extract text from images using OCR
• Remove text from images using inpainting
• Translate Shopify product images at scale

Installation

From npm

npm install @translateimage/mcp-server
# or
pnpm add @translateimage/mcp-server

From source

git clone https://github.com/translateimage/mcp-server
cd mcp-server
pnpm install
pnpm build

Quick Start

Get Your API Key

1. Go to TranslateImage Dashboard
2. Navigate to Settings → API Keys
3. Create a new API key for MCP integration

AI Agent Integration

Add to your AI Agent configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "translateimage": {
      "command": "npx",
      "args": ["@translateimage/mcp-server"],
      "env": {
        "TRANSLATEIMAGE_API_KEY": "your-translateimage-api-key"
      }
    }
  }
}

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

HTTP Server

For remote access or web integrations:

# Set environment variables
export TRANSLATEIMAGE_API_KEY=your-translateimage-api-key
export PORT=3001
export ALLOWED_ORIGINS=http://localhost:3000

# Start HTTP server
npx @translateimage/mcp-server --http

Or run directly:

node dist/bin/http.js

The HTTP server exposes a single endpoint:

• POST /mcp - JSON-RPC endpoint for MCP requests
• GET /mcp - Returns 405 (SSE not supported in stateless mode)

Environment Variables

| Variable | Required | Description | | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- | | TRANSLATEIMAGE_API_KEY | Yes | Your TranslateImage API key from the dashboard. Required for all tools. | | ALLOWED_ORIGINS | No | Comma-separated list of allowed CORS origins for HTTP server. Default: http://localhost:3000,http://localhost:3001 | | PORT | No | HTTP server port. Default: 3001 |

Tools Reference

Core Tools

translate_image

Translate text in images while preserving the original layout. Detects text, translates it to the target language, and renders the translation back onto the image.

Input:

| Parameter | Type | Required | Description | | ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | image | object | Yes | Image input (see Image Input) | | target_lang | string | Yes | Target language code (e.g., "en", "ja", "zh", "es") | | translator | string | Yes | Translator model: "gemini-2.5-flash", "deepseek", "grok-4-fast", "kimi-k2", "gemini-3-flash", "gpt-5.1" | | font | string | No | Font for rendered text: "NotoSans" (default), "WildWords", "BadComic", "MaShanZheng", "KomikaJam", "Bangers", "Edo", "RIDIBatang", "Bushidoo", "Hayah", "Itim", "Mogul Irina" |

Output:

| Field | Type | Description | | ----------------- | ------ | ---------------------------------------------------------- | | translatedImage | string | Base64-encoded translated image (PNG) | | inpaintedImage | string | Base64-encoded image with text removed | | textRegions | array | Array of detected/translated text regions with positioning |

Example:

{
  "image": { "url": "https://example.com/manga-page.jpg" },
  "target_lang": "en",
  "translator": "gemini-2.5-flash",
  "font": "WildWords"
}

extract_text

Extract text from images using OCR (Optical Character Recognition). Returns detected paragraphs with bounding boxes and detected language information.

Input:

| Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------- | | image | object | Yes | Image input (see Image Input) |

Output:

| Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------- | | paragraphs | array | Array of detected paragraphs with text, bounding boxes, and language info | | width | number | Image width in pixels | | height | number | Image height in pixels | | angle | number | Detected text angle/rotation in degrees |

Paragraph structure:

{
  boundingBox: [x1, y1, x2, y2],  // Bounding box coordinates
  text: string,                   // Paragraph text
  lines: [{                       // Array of lines
    boundingBox: [x1, y1, x2, y2],
    text: string,
    words: [{
      boundingBox: [x1, y1, x2, y2],
      text: string,
      confidence: number  // 0-1
    }]
  }],
  detectedLanguage: {
    language: string,    // Language name
    code: string,        // Language code
    confidence: number   // 0-1
  }
}

Example:

{
  "image": { "base64": "iVBORw0KGgo...", "mimeType": "image/png" }
}

remove_text

Remove text from images using inpainting. Detects text regions and fills them with appropriate background content.

Input:

| Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------- | | image | object | Yes | Image input (see Image Input) |

Output:

| Field | Type | Description | | -------------- | ------ | ------------------------------------------------------ | | cleanedImage | string | Base64-encoded image with text removed/inpainted (PNG) |

Example:

{
  "image": { "url": "https://example.com/image-with-text.png" }
}

image_to_text

Extract text from images using AI and optionally translate to specified languages. Provides high-quality OCR with language detection and translation capabilities.

Input:

| Parameter | Type | Required | Description | | ----------------- | -------- | -------- | --------------------------------------------- | | image | object | Yes | Image input (see Image Input) | | targetLanguages | string[] | No | Target language codes for translation |

Output:

| Field | Type | Description | | ------------------ | ------ | ------------------------------------------------------------------- | | extractedText | string | Text extracted from the image | | detectedLanguage | string | Detected language of the extracted text | | translations | object | Translations keyed by language code (if targetLanguages provided) |

Example:

{
  "image": { "url": "https://example.com/document.jpg" },
  "targetLanguages": ["en", "es", "fr"]
}

Shopify Tools

shopify_translate_product

Translate product images for a Shopify store. Fetches product media from Shopify and translates text in images to the target language.

Input:

| Parameter | Type | Required | Description | | -------------------------------- | ------ | -------- | -------------------------------------------- | | shopifyCredentials | object | Yes | Shopify credentials | | shopifyCredentials.shopDomain | string | Yes | Shop domain (e.g., "myshop.myshopify.com") | | shopifyCredentials.accessToken | string | Yes | Shopify API access token | | productId | string | Yes | Shopify product ID | | targetLanguage | string | Yes | Target language code | | translator | string | Yes | Translator model |

Output:

| Field | Type | Description | | ------------------ | ------ | --------------------------- | | productId | string | Shopify product ID | | productTitle | string | Product title | | status | string | Translation status | | imagesTranslated | number | Number of images translated |

Example:

{
  "shopifyCredentials": {
    "shopDomain": "myshop.myshopify.com",
    "accessToken": "shpat_xxxxx"
  },
  "productId": "gid://shopify/Product/123456789",
  "targetLanguage": "ja",
  "translator": "gemini-2.5-flash"
}

shopify_batch_translate

Batch translate product images for multiple Shopify products.

Input:

| Parameter | Type | Required | Description | | -------------------- | -------- | -------- | ---------------------------- | | shopifyCredentials | object | Yes | Shopify credentials | | productIds | string[] | Yes | Array of Shopify product IDs | | targetLanguage | string | Yes | Target language code | | translator | string | Yes | Translator model |

Output:

| Field | Type | Description | | ---------------- | ------ | -------------------------- | | totalProducts | number | Total products processed | | successCount | number | Successful translations | | failureCount | number | Failed translations | | targetLanguage | string | Target language used | | results | array | Individual product results |

Example:

{
  "shopifyCredentials": {
    "shopDomain": "myshop.myshopify.com",
    "accessToken": "shpat_xxxxx"
  },
  "productIds": ["gid://shopify/Product/123", "gid://shopify/Product/456"],
  "targetLanguage": "en",
  "translator": "deepseek"
}

shopify_shop_stats

Get statistics about a Shopify shop including total products, products with images, and total image count.

Input:

| Parameter | Type | Required | Description | | -------------------- | ------ | -------- | ------------------- | | shopifyCredentials | object | Yes | Shopify credentials |

Output:

| Field | Type | Description | | -------------------- | ------- | ------------------------------------- | | shopName | string | Shop name | | totalProducts | number | Total products in shop | | productsWithImages | number | Products with at least one image | | totalImages | number | Total image count | | isPartial | boolean | Whether scan was partial (large shop) |

Example:

{
  "shopifyCredentials": {
    "shopDomain": "myshop.myshopify.com",
    "accessToken": "shpat_xxxxx"
  }
}

shopify_scan_products

Scan Shopify product images for text detection. Identifies which images contain translatable text.

Input:

| Parameter | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------- | | shopifyCredentials | object | Yes | Shopify credentials | | productId | string | No | Specific product ID to scan | | maxProducts | number | No | Max products to scan (default: 10, max: 50) |

Output:

| Field | Type | Description | | ----------------- | ------- | ------------------------- | | productsScanned | number | Products scanned | | imagesScanned | number | Images scanned | | imagesWithText | number | Images with detected text | | isPartial | boolean | Whether scan was partial | | stoppedReason | string | Reason if stopped early | | results | array | Detailed scan results |

Example:

{
  "shopifyCredentials": {
    "shopDomain": "myshop.myshopify.com",
    "accessToken": "shpat_xxxxx"
  },
  "productId": "gid://shopify/Product/123456789"
}

Image Input

All tools that accept images support three input methods:

URL

{
  "image": {
    "url": "https://example.com/image.jpg"
  }
}

Base64 with MIME type

{
  "image": {
    "base64": "iVBORw0KGgo...",
    "mimeType": "image/png"
  }
}

Data URL

{
  "image": {
    "base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Supported MIME types: image/jpeg, image/png, image/webp, image/gif

Size limit: 10MB

Programmatic Usage

import { createMcpServer, McpServerConfig } from "@translateimage/mcp-server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const config: McpServerConfig = {
  // Server-side configuration (loaded from environment)
};

const server = createMcpServer(config);
const transport = new StdioServerTransport();

await server.connect(transport);

Development

# Install dependencies
pnpm install

# Type check
pnpm typecheck

# Build
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test --coverage

Architecture

packages/mcp-server/
├── src/
│   ├── index.ts          # Package exports
│   ├── server.ts         # createMcpServer factory
│   ├── schemas/          # Zod schemas for all tools
│   ├── utils/            # Image handling, errors, config
│   └── tools/            # Tool implementations
│       ├── index.ts      # Tool registration
│       ├── translate.ts  # translate_image
│       ├── ocr.ts        # extract_text
│       ├── text-removal.ts # remove_text
│       ├── image-to-text.ts # image_to_text
│       └── shopify/      # Shopify integration tools
├── bin/
│   ├── stdio.ts          # CLI entry point
│   └── http.ts           # HTTP server entry point
└── __tests__/            # Test files

Troubleshooting

"API key missing" error

Ensure you've set your TranslateImage API key:

export TRANSLATEIMAGE_API_KEY=your-api-key

Or in AI Agent config, add it to the env section.

"Origin not allowed" error (HTTP server)

Add your origin to ALLOWED_ORIGINS:

export ALLOWED_ORIGINS=http://localhost:3000,http://yourdomain.com

Image size exceeds limit

Images must be under 10MB. Compress or resize large images before sending.

AI Agent not detecting server

1. Ensure the config file path is correct for your OS
2. Restart AI Agent after config changes
3. Check that npx @translateimage/mcp-server runs without errors

HTTP server returns 405

The HTTP server runs in stateless mode and doesn't support SSE. Use POST requests to /mcp only.

API Key & Billing

• Get your API key from the TranslateImage Dashboard
• Usage is billed based on your subscription plan
• Monitor usage in the dashboard under Settings → Usage

License

Proprietary - All rights reserved