Weblate MCP Server
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"
}
📊 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 stringsstate:=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
🏗️ 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
- Create tool file in
src/tools/ - Implement MCP tool interface
- Add to service providers
- Write tests
- 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:
- Fork the repository
- Create a feature branch from main
- Implement changes with tests
- Update documentation
- 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!