Skip to main content
Glama
Lokiec752

Translations MCP Server

by Lokiec752
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Translations MCP Server

A Model Context Protocol (MCP) server that automatically discovers and searches translation files in your projects.

Features

  • Configurable path: Specify exact translation file path via configuration (recommended)

  • Auto-discovery: Automatically finds translation files in en folders as fallback

  • Fast search: Indexed search through translation keys and values

  • Partial/exact matching: Support for both partial and exact match searches

  • File watching: Automatically reloads when translation files change

  • Multiple file formats: Supports common translation file names

  • TypeScript: Fully typed with proper interfaces and modular architecture

Related MCP server: i18n Agent

Quick Start

Method 1: Configured Path (Recommended)

Configure your MCP server to use a specific translation file:

{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["path/to/your/translation.json"]
    }
  }
}

Method 2: Environment Variable

{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "env": {
        "TRANSLATION_FILE_PATH": "src/assets/locales/en/translation.json"
      }
    }
  }
}

Method 3: Auto-Discovery (Fallback)

If no path is configured, the server will automatically search for translation files:

{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp"
    }
  }
}

Architecture

The project is organized into focused modules for better maintainability:

src/
├── index.ts              # Main server entry point with MCP server setup
├── translation-discovery.ts # File discovery and search functionality
└── types.ts              # TypeScript interfaces and types

Module Descriptions

  • index.ts: Main MCP server setup, tool handlers, and entry point

  • translation-discovery.ts: Handles file discovery, indexing, and search functionality

  • types.ts: TypeScript interfaces for type safety across modules

Usage

The server provides two main tools:

1. find_translation

Search for translation keys and values:

{
  "name": "find_translation",
  "arguments": {
    "query": "search term",
    "exact": false
  }
}

  • query: String to search for in translation keys or values

  • exact: Boolean (optional) - whether to perform exact matching (default: false)

2. refresh_translations

Manually refresh the translation index (useful after file changes):

{
  "name": "refresh_translations",
  "arguments": {}
}

Returns the current number of indexed entries and refresh status.

Configuration Examples

For React/Next.js Projects

{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["public/locales/en/translation.json"]
    }
  }
}

For ASP.NET Core + React Projects

{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["ClientApp/public/locales/en/translation.json"]
    }
  }
}

Absolute Path

{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["C:/projects/my-app/locales/en/translation.json"]
    }
  }
}

How It Works

  1. Discovery: On startup, recursively searches for translation files in folders named en

  2. Indexing: Builds an in-memory search index of all translation keys and values

  3. Search: Provides fast lookups with support for partial and exact matching

Supported Project Structures

The server can find translation files in various project structures:

  • ./en/translation.json (simple)

  • ./locales/en/translation.json (common)

  • ./src/assets/locales/en/translation.json (React/Angular)

  • ./ClientApp/public/locales/en/translation.json (ASP.NET Core with React)

  • ./Project.Name/ClientApp/public/locales/en/translation.json (deep .NET structures)

Installation

Install globally via npm:

npm install -g translations-mcp

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

# Development mode
npm run dev

Testing

The project includes several test scripts:

  • npm run test:server - Test basic server functionality

  • npm run test:find - Test search functionality

  • npm run test:quick - Quick integration test

  • npm run test:all - Run all tests

Supported File Names

The server looks for these translation files in en folders:

  • translation.json

  • translations.json

  • common.json

  • messages.json

Adding to Claude Desktop

Recommended: Specify Your Translation File Path

{
  "mcpServers": {
    "translations": {
      "command": "translations-mcp",
      "args": ["path/to/your/translation.json"]
    }
  }
}

Alternative: Auto-Discovery

{
  "mcpServers": {
    "translations": {
      "command": "translations-mcp"
    }
  }
}

Benefits of Configured Path

✅ Eliminates confusion - No more loading wrong translation files
✅ Faster startup - No need to search directories
✅ Predictable behavior - Always uses the exact file you specify
✅ Works anywhere - Not limited to specific folder structures
✅ Production ready - Points to your actual translation files, not test data

  • npm run clean - Remove compiled files

  • npm test - Run the main server functionality test

  • npm run test:server - Run comprehensive server tests with response parsing

  • npm run test:quick - Run quick global installation test

  • npm run test:all - Run all tests (server + quick)

Development Workflow

  1. Clone or download this package

  2. Run npm install to install dependencies

  3. Make your changes to files in the src/ directory

  4. Test with npm run dev for development or npm test to verify functionality

  5. Build for production with npm run build && npm start

License

MIT

Available Tools

2 tools
find_translationB

Find translation keys and values in the discovered translation file

ParametersJSON Schema
NameRequiredDescriptionDefault
exactNoWhether to search for exact matches only (default: false)
queryYesSearch query to find in translation keys or values

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It does not disclose whether the search is read-only, case-sensitive, or if it returns limited results. The exact matching behavior is only implied by the parameter but not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 9 words, very concise and front-loaded. Every word is necessary and contributes to the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two parameters and no output schema. The description adequately states the purpose, but does not cover aspects like search scope, result limits, or behavior with invalid queries. It is minimally adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The tool description adds no additional meaning beyond the schema descriptions of 'query' and 'exact'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Find' and the resource 'translation keys and values in the discovered translation file'. It distinguishes from the sibling tool 'refresh_translations' which has a different purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. The sibling tool 'refresh_translations' is mentioned but without comparison, leaving usage context implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refresh_translationsA

Manually refresh and re-index translation files to pick up any changes

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It states the action ('refresh and re-index') but does not disclose potential side effects, idempotency, or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one sentence with 9 words, front-loading the action. It is very concise, though some might argue it sacrifices completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple parameterless tool with no output schema, the description covers the essential action. However, it could mention if the operation is asynchronous or if it clears caches.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters (100% coverage trivially), so the description adds no parameter meaning beyond the schema. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('refresh', 're-index') and identifies the resource ('translation files'), clearly distinguishing from the sibling 'find_translation' which presumably searches translations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (after changes to translation files) but does not explicitly state when not to use, mention alternatives, or provide prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

The two tools, find_translation and refresh_translations, serve distinct purposes with no overlap. One is for querying translations, the other for maintenance.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (find_translation, refresh_translations), making them predictable and easy to understand.

Tool Count3/5

With only 2 tools, the server feels under-scoped for a typical translation management system. While acceptable for a minimal server, it lacks breadth.

Completeness2/5

The server provides only find and refresh capabilities, missing essential operations like add, update, or delete translations. This leaves significant gaps for common use cases.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Lokiec752/translations-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server