🌍 MCP-Localization-Engine

Global localization data for 174 locales via MCP (Model Context Protocol)

🎯 What is this?

A Model Context Protocol (MCP) server that provides comprehensive localization data for 174 locales worldwide. Perfect for AI agents and applications that need to generate culturally-adapted multilingual content.

Related MCP server: Countries MCP Server

✨ Features

• 174 Locales: Complete coverage across Europe, Asia, Americas, Middle East, Africa, and Oceania

• 3 MCP Tools:

  • get_locale_config: Technical metadata (timezone, currency, script, etc.)

  • get_cultural_data: Cultural adaptation data (values, tone, references)

  • get_rules: Global rules (slug generation, SEO, content adaptation)

• Smart Caching: 24-hour TTL with 98% hit rate

• Fast: 2-5ms response time (cached), 50ms (cold)

• Production Ready: Validated schemas, error handling, comprehensive tests

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/supernovae/mcp-localization-engine.git
cd mcp-localization-engine

# Install dependencies
pip install -r requirements.txt

# Verify installation
python src/server.py --version

Running the MCP Server

# Start the server
python src/server.py

# Output:
# 🚀 MCP-Localization-Engine v1.0.0
# 📂 Loaded 174 locales
# 💾 Cache initialized (TTL: 24h)
# ✅ Server ready on stdio

Configure with Claude Desktop

macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "localization": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/mcp-localization-engine/src/server.py"]
    }
  }
}

⚠️ Replace /ABSOLUTE/PATH/TO/ with your actual path!

Restart Claude Desktop to load the configuration.

Test in Claude

Open Claude and try:

"Use the localization MCP to get the configuration for French (France)"

Claude should call get_locale_config("fr-FR") and return technical data!

📚 Documentation

• Complete Documentation - Full guides in docs/ folder

• Architecture - System architecture

• MCP Tools - Detailed tool documentation

• Quick Start - 10-minute setup guide

• Development - Contributing guide

🔧 Usage Example

from src.loader import load_locale_config, load_cultural_data

# Get technical config
config = load_locale_config("ja-JP")
print(config["timezone"])    # "Asia/Tokyo"
print(config["currency"])    # "JPY"
print(config["script"])      # "CJK"

# Get cultural data
cultural = load_cultural_data("ja-JP")
print(cultural["cultural_values"])  # ["Harmony (和)", "Respect for hierarchy", ...]
print(cultural["tone_preferences"]["business"])  # "Formal, polite, humble"

🌍 Supported Locales

174 locales across:

• 🇪🇺 Europe: 75 locales

• 🌏 Asia: 45 locales

• 🌎 Americas: 20 locales

• 🌍 Middle East: 20 locales

• 🌍 Africa: 9 locales

• 🇦🇺 Oceania: 5 locales

View complete list →

🧪 Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Validate all locale data
python tests/validate_data.py

# Run specific test
pytest tests/test_tools.py -v

🛠️ Development

# Install dev dependencies
pip install -r requirements-dev.txt

# Generate a new locale template
python scripts/generate_locale.py pt-BR

# List all locales
python scripts/list_locales.py

# Benchmark performance
python scripts/benchmark.py

📊 Project Stats

• Code: ~1,000 lines of Python

• Data: ~4.5 MB (174 configs + 174 culturals + 3 rules)

• Tests: 20+ test cases

• Cache Hit Rate: 98%

• Response Time: 2-5ms (cached), 50ms (cold)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Adding a New Locale

1. Generate template: python scripts/generate_locale.py xx-YY

2. Fill in the data in data/locales/config/xx-YY.json and data/locales/cultural/xx-YY.json

3. Validate: python tests/validate_data.py --locale xx-YY

4. Submit PR

📄 License

MIT License - see LICENSE

🔗 Links

• GitHub Repository

• Documentation

• Issues

• MCP Protocol

💡 Use Cases

• Content Generation: Generate culturally-adapted marketing content

• SEO Optimization: Get locale-specific SEO rules

• URL Generation: Generate proper slugs per locale

• Cultural Adaptation: Avoid cultural faux-pas

• Multi-project: Shared foundation for all your localization needs

🏢 Built by SuperNovae Studio

Made with ❤️ for the global developer community.

Questions? Open an issue or check the docs!