mmntm/weblate-mcp

A Model Context Protocol (MCP) server that provides seamless integration with Weblate translation management platform. This server enables AI assistants to interact directly with your Weblate instance for comprehensive translation management.

🌟 Features

• 🔧 Complete Weblate API Access: Full integration with Weblate's REST API
• 🤖 AI-Powered Workflow: Natural language interaction with your translation projects
• 📊 Project Management: Create, list, and manage translation projects
• 🔍 Component Operations: Handle translation components and configurations
• ✏️ Translation Management: Update, search, and manage translations
• 🌐 Language Support: Work with all supported languages in your Weblate instance
• 🚀 Multiple Transports: HTTP/SSE, Streamable HTTP, and STDIO support
• 🛡️ Type Safety: Full TypeScript implementation with comprehensive error handling
• ⚡ LLM-Optimized: Tools designed to guide AI models toward efficient usage patterns

🎯 What is This?

This MCP server acts as a bridge between AI assistants (like Claude Desktop) and your Weblate translation management platform. Instead of manually navigating the Weblate web interface, you can use natural language to:

• "List all projects in my Weblate instance"
• "Show me the French translations for the frontend component"
• "Update the welcome message translation"
• "Create a new translation project"

🚀 Quick Start

Option 1: Use with npx (Recommended)

The easiest way to use this MCP server is with npx - no installation required!

For Claude Desktop or other MCP clients:

{
  "mcpServers": {
    "weblate": {
      "command": "npx",
      "args": ["-y", "@mmntm/weblate-mcp"],
      "env": {
        "WEBLATE_API_URL": "https://your-weblate-instance.com/api",
        "WEBLATE_API_TOKEN": "your-weblate-api-token"
      }
    }
  }
}

Manual testing:

# Test the server directly
npx @mmntm/weblate-mcp

Option 2: Development Setup

Prerequisites

• Node.js 18+
• pnpm package manager
• Weblate instance with API access

Installation

# Clone and install
git clone <this-repo>
cd weblate-mcp
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your Weblate API URL and token

# Build and start
pnpm build
pnpm start

Server runs on http://localhost:3001 by default.

Environment Configuration

WEBLATE_API_URL=https://your-weblate-instance.com
WEBLATE_API_TOKEN=your-api-token-here
PORT=3001
NODE_ENV=production
LOG_LEVEL=info

🔗 MCP Client Configuration

Claude Desktop (npx method - Recommended)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "weblate": {
      "command": "npx",
      "args": ["-y", "@mmntm/weblate-mcp"],
      "env": {
        "WEBLATE_API_URL": "https://your-weblate-instance.com/api",
        "WEBLATE_API_TOKEN": "your-weblate-api-token"
      }
    }
  }
}

Claude Desktop (Development/Local)

For development or local builds:

{
  "mcpServers": {
    "weblate": {
      "command": "node",
      "args": ["/path/to/weblate-mcp/dist/main.js"],
      "env": {
        "WEBLATE_API_URL": "https://your-weblate-instance.com/api",
        "WEBLATE_API_TOKEN": "your-api-token"
      }
    }
  }
}

HTTP Clients (Cursor, VS Code, Web Apps)

{
  "transport": "http",
  "url": "http://localhost:3001/mcp"
}

🛠️ Available Tools

📊 Project Management

Tool	Description
listProjects	List all available Weblate projects with URLs and metadata

🔧 Component Management

Tool	Description
listComponents	List components in a specific project with source language details

✏️ Translation Management

Tool	Description
searchUnitsWithFilters ⭐	Efficient search using Weblate's native filtering syntax
searchStringInProject	Search for translations containing specific text in a project
getTranslationForKey	Get translation value for a specific key
writeTranslation	Update or write translation values with approval support
bulkWriteTranslations ⚡	Batch update multiple translations efficiently with error handling
findTranslationsForKey	Find all translations for a specific key across languages

🚀 Why searchUnitsWithFilters is Recommended

The searchUnitsWithFilters tool uses Weblate's native filtering syntax, making it the most efficient way to find translations:

• ❌ Inefficient: Getting all keys then checking each one individually (can make thousands of API calls)
• ✅ Efficient: Single filtered search using Weblate's query syntax

Example efficient queries:

• state:=0 - Find untranslated strings
• state:=10 - Find strings that need editing
• source:"login" - Find strings containing "login"
• component:common AND state:=0 - Complex filters

🌐 Language Management

Tool	Description
listLanguages	List languages available in a specific project

📊 Translation Statistics Dashboard

Tool	Description
getProjectStatistics	Comprehensive project statistics with completion rates and string counts
getComponentStatistics	Detailed statistics for a specific component
getProjectDashboard	Complete dashboard overview with all component statistics
getTranslationStatistics	Statistics for specific translation (project/component/language)
getComponentLanguageProgress	Translation progress for all languages in a component with progress bars
getLanguageStatistics	Statistics for a language across all projects
getUserStatistics	User contribution statistics and activity metrics

📈 Change Tracking & History

Tool	Description
listRecentChanges	Recent changes across all projects with user and timestamp filtering
getProjectChanges	Recent changes for a specific project
getComponentChanges	Recent changes for a specific component
getChangesByUser	Recent changes by a specific user

💡 Usage Examples

Project Operations

// List all projects
await list_projects();

// Get specific project details
await get_project({ slug: "my-project" });

// Create a new project
await create_project({
  name: "New Project",
  slug: "new-project",
  web: "https://example.com"
});

Translation Operations

// List translations for a component
await list_translations({
  project_slug: "my-project",
  component_slug: "frontend"
});

// Get specific translation
await get_translation({
  project_slug: "my-project",
  component_slug: "frontend",
  language_code: "fr"
});

// Update translations
await update_translation({
  project_slug: "my-project",
  component_slug: "frontend",
  language_code: "fr",
  translations: {
    "welcome": "Bienvenue",
    "goodbye": "Au revoir"
  }
});

📚 Documentation

Document	Description
📖 Documentation Hub	Complete documentation overview and quick start
🚀 Installation & Setup	Installation, configuration, and Claude Desktop setup
📋 API Reference	Complete API documentation with examples
🛠️ Development Guide	Contributing, development setup, and testing
🏗️ Architecture	Codebase structure, patterns, and design decisions
📦 Release Process	Release management and publishing workflow
🔄 Changesets Guide	Version management with changesets

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  Weblate MCP     │───▶│  Weblate API    │
│  (IDE/Editor)   │    │     Server       │    │   (REST API)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   MCP Tools      │
                       │ • Projects       │
                       │ • Components     │
                       │ • Translations   │
                       │ • Languages      │
                       └──────────────────┘

Technology Stack:

• NestJS: Modern Node.js framework with dependency injection
• TypeScript: Full type safety and IntelliSense support
• Weblate REST API: Comprehensive API wrapper with interfaces
• MCP Protocol: Standard Model Context Protocol implementation
• Axios: HTTP client for API communication

🧪 Development

Development Setup

# Start development server with hot reload
pnpm run dev

# Run tests
pnpm test

# Run end-to-end tests
pnpm run test:e2e

# Generate test coverage
pnpm run test:cov

# Build for production
pnpm build

Adding New Tools

1. Create tool file in src/tools/
2. Implement MCP tool interface
3. Add to service providers
4. Write tests
5. Update documentation

See Development Guide for detailed instructions.

🎯 Use Cases

Translation Management

• Project oversight: Monitor translation progress across projects
• Content updates: Update translations programmatically
• Quality assurance: Review and approve translations
• Team coordination: Manage translation workflows

Development Integration

• CI/CD pipelines: Automate translation updates in deployment
• Content management: Sync translations with content systems
• Localization testing: Validate translations in different contexts
• Documentation: Generate translation reports and statistics

AI-Assisted Workflows

• Natural language queries: Ask about translation status in plain English
• Contextual operations: AI understands your translation needs
• Batch operations: Perform bulk updates with AI assistance
• Smart suggestions: Get AI-powered translation recommendations

🔒 Security & Production

• API Token Security: Store tokens securely, use environment variables
• Rate Limiting: Built-in request throttling and retry logic
• Error Handling: Comprehensive error responses with debugging info
• Input Validation: All inputs validated with Zod schemas
• HTTPS Support: Secure communication with Weblate instances

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines:

1. Fork the repository
2. Create a feature branch from main
3. Implement changes with tests
4. Update documentation
5. Submit a pull request

Code Style

• Use TypeScript for type safety
• Follow NestJS conventions
• Add comprehensive tests
• Update documentation

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Weblate: For providing an excellent translation management platform
• Model Context Protocol: For the standardized protocol specification
• NestJS: For the robust application framework
• Contributors: Everyone who helps improve this project

---

Built with ❤️ for the translation community

Need help? Check our documentation or create an issue!