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. - 🔧 Complete Weblate API Access: Full integration with Weblate's REST API - 🤖 AI-Powered Workflow: Natural language interaction with your translation proje
Add this skill
npx mdskills install mmntm/weblate-mcpComprehensive MCP server for Weblate translation management with excellent documentation and robust toolset
1# Weblate MCP Server23A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.45## 🌟 Features67- **🔧 Complete Weblate API Access**: Full integration with Weblate's REST API8- **🤖 AI-Powered Workflow**: Natural language interaction with your translation projects9- **📊 Project Management**: Create, list, and manage translation projects10- **🔍 Component Operations**: Handle translation components and configurations11- **✏️ Translation Management**: Update, search, and manage translations12- **🌐 Language Support**: Work with all supported languages in your Weblate instance13- **🚀 Multiple Transports**: HTTP/SSE, Streamable HTTP, and STDIO support14- **🛡️ Type Safety**: Full TypeScript implementation with comprehensive error handling15- **⚡ LLM-Optimized**: Tools designed to guide AI models toward efficient usage patterns1617## 🎯 What is This?1819This 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:2021- **"List all projects in my Weblate instance"**22- **"Show me the French translations for the frontend component"**23- **"Update the welcome message translation"**24- **"Create a new translation project"**2526## 🚀 Quick Start2728### Option 1: Use with npx (Recommended)2930The easiest way to use this MCP server is with npx - no installation required!3132**For Claude Desktop or other MCP clients:**33```json34{35 "mcpServers": {36 "weblate": {37 "command": "npx",38 "args": ["-y", "@mmntm/weblate-mcp"],39 "env": {40 "WEBLATE_API_URL": "https://your-weblate-instance.com/api",41 "WEBLATE_API_TOKEN": "your-weblate-api-token"42 }43 }44 }45}46```4748**Manual testing:**49```bash50# Test the server directly51npx @mmntm/weblate-mcp52```5354### Option 2: Development Setup5556### Prerequisites57- Node.js 18+58- pnpm package manager59- Weblate instance with API access6061### Installation62```bash63# Clone and install64git clone <this-repo>65cd weblate-mcp66pnpm install6768# Configure environment69cp .env.example .env70# Edit .env with your Weblate API URL and token7172# Build and start73pnpm build74pnpm start75```7677Server runs on `http://localhost:3001` by default.7879### Environment Configuration80```env81WEBLATE_API_URL=https://your-weblate-instance.com82WEBLATE_API_TOKEN=your-api-token-here83PORT=300184NODE_ENV=production85LOG_LEVEL=info86```8788## 🔗 MCP Client Configuration8990### Claude Desktop (npx method - Recommended)91Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):92```json93{94 "mcpServers": {95 "weblate": {96 "command": "npx",97 "args": ["-y", "@mmntm/weblate-mcp"],98 "env": {99 "WEBLATE_API_URL": "https://your-weblate-instance.com/api",100 "WEBLATE_API_TOKEN": "your-weblate-api-token"101 }102 }103 }104}105```106107### Claude Desktop (Development/Local)108For development or local builds:109```json110{111 "mcpServers": {112 "weblate": {113 "command": "node",114 "args": ["/path/to/weblate-mcp/dist/main.js"],115 "env": {116 "WEBLATE_API_URL": "https://your-weblate-instance.com/api",117 "WEBLATE_API_TOKEN": "your-api-token"118 }119 }120 }121}122```123124### HTTP Clients (Cursor, VS Code, Web Apps)125```json126{127 "transport": "http",128 "url": "http://localhost:3001/mcp"129}130```131132## 🛠️ Available Tools133134### 📊 Project Management135| Tool | Description |136|------|-------------|137| **`listProjects`** | List all available Weblate projects with URLs and metadata |138139### 🔧 Component Management140| Tool | Description |141|------|-------------|142| **`listComponents`** | List components in a specific project with source language details |143144### ✏️ Translation Management145| Tool | Description |146|------|-------------|147| **`searchUnitsWithFilters`** ⭐ | **Efficient search using Weblate's native filtering syntax** |148| **`searchStringInProject`** | Search for translations containing specific text in a project |149| **`getTranslationForKey`** | Get translation value for a specific key |150| **`writeTranslation`** | Update or write translation values with approval support |151| **`bulkWriteTranslations`** ⚡ | **Batch update multiple translations efficiently with error handling** |152| **`findTranslationsForKey`** | Find all translations for a specific key across languages |153154#### 🚀 Why searchUnitsWithFilters is Recommended155156The `searchUnitsWithFilters` tool uses Weblate's native filtering syntax, making it the most efficient way to find translations:157158- **❌ Inefficient**: Getting all keys then checking each one individually (can make thousands of API calls)159- **✅ Efficient**: Single filtered search using Weblate's query syntax160161**Example efficient queries:**162- `state:=0` - Find untranslated strings163- `state:=10` - Find strings that need editing164- `source:"login"` - Find strings containing "login"165- `component:common AND state:=0` - Complex filters166167### 🌐 Language Management168| Tool | Description |169|------|-------------|170| **`listLanguages`** | List languages available in a specific project |171172### 📊 Translation Statistics Dashboard173| Tool | Description |174|------|-------------|175| **`getProjectStatistics`** | Comprehensive project statistics with completion rates and string counts |176| **`getComponentStatistics`** | Detailed statistics for a specific component |177| **`getProjectDashboard`** | Complete dashboard overview with all component statistics |178| **`getTranslationStatistics`** | Statistics for specific translation (project/component/language) |179| **`getComponentLanguageProgress`** | Translation progress for all languages in a component with progress bars |180| **`getLanguageStatistics`** | Statistics for a language across all projects |181| **`getUserStatistics`** | User contribution statistics and activity metrics |182183### 📈 Change Tracking & History184| Tool | Description |185|------|-------------|186| **`listRecentChanges`** | Recent changes across all projects with user and timestamp filtering |187| **`getProjectChanges`** | Recent changes for a specific project |188| **`getComponentChanges`** | Recent changes for a specific component |189| **`getChangesByUser`** | Recent changes by a specific user |190191## 💡 Usage Examples192193### Project Operations194```typescript195// List all projects196await list_projects();197198// Get specific project details199await get_project({ slug: "my-project" });200201// Create a new project202await create_project({203 name: "New Project",204 slug: "new-project",205 web: "https://example.com"206});207```208209### Translation Operations210```typescript211// List translations for a component212await list_translations({213 project_slug: "my-project",214 component_slug: "frontend"215});216217// Get specific translation218await get_translation({219 project_slug: "my-project",220 component_slug: "frontend",221 language_code: "fr"222});223224// Update translations225await update_translation({226 project_slug: "my-project",227 component_slug: "frontend",228 language_code: "fr",229 translations: {230 "welcome": "Bienvenue",231 "goodbye": "Au revoir"232 }233});234```235236## 📚 Documentation237238| Document | Description |239|----------|-------------|240| **[📖 Documentation Hub](./docs/README.md)** | Complete documentation overview and quick start |241| **[🚀 Installation & Setup](./docs/MCP_SETUP.md)** | Installation, configuration, and Claude Desktop setup |242| **[📋 API Reference](./docs/API.md)** | Complete API documentation with examples |243| **[🛠️ Development Guide](./docs/DEVELOPMENT.md)** | Contributing, development setup, and testing |244| **[🏗️ Architecture](./docs/ARCHITECTURE.md)** | Codebase structure, patterns, and design decisions |245| **[📦 Release Process](./docs/RELEASE.md)** | Release management and publishing workflow |246| **[🔄 Changesets Guide](./docs/CHANGESETS.md)** | Version management with changesets |247248## 🏗️ Architecture249250```251┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐252│ MCP Client │───▶│ Weblate MCP │───▶│ Weblate API │253│ (IDE/Editor) │ │ Server │ │ (REST API) │254└─────────────────┘ └──────────────────┘ └─────────────────┘255 │256 ▼257 ┌──────────────────┐258 │ MCP Tools │259 │ • Projects │260 │ • Components │261 │ • Translations │262 │ • Languages │263 └──────────────────┘264```265266**Technology Stack:**267- **NestJS**: Modern Node.js framework with dependency injection268- **TypeScript**: Full type safety and IntelliSense support269- **Weblate REST API**: Comprehensive API wrapper with interfaces270- **MCP Protocol**: Standard Model Context Protocol implementation271- **Axios**: HTTP client for API communication272273## 🧪 Development274275### Development Setup276```bash277# Start development server with hot reload278pnpm run dev279280# Run tests281pnpm test282283# Run end-to-end tests284pnpm run test:e2e285286# Generate test coverage287pnpm run test:cov288289# Build for production290pnpm build291```292293### Adding New Tools2941. Create tool file in `src/tools/`2952. Implement MCP tool interface2963. Add to service providers2974. Write tests2985. Update documentation299300See [Development Guide](./docs/DEVELOPMENT.md) for detailed instructions.301302## 🎯 Use Cases303304### Translation Management305- **Project oversight**: Monitor translation progress across projects306- **Content updates**: Update translations programmatically307- **Quality assurance**: Review and approve translations308- **Team coordination**: Manage translation workflows309310### Development Integration311- **CI/CD pipelines**: Automate translation updates in deployment312- **Content management**: Sync translations with content systems313- **Localization testing**: Validate translations in different contexts314- **Documentation**: Generate translation reports and statistics315316### AI-Assisted Workflows317- **Natural language queries**: Ask about translation status in plain English318- **Contextual operations**: AI understands your translation needs319- **Batch operations**: Perform bulk updates with AI assistance320- **Smart suggestions**: Get AI-powered translation recommendations321322## 🔒 Security & Production323324- **API Token Security**: Store tokens securely, use environment variables325- **Rate Limiting**: Built-in request throttling and retry logic326- **Error Handling**: Comprehensive error responses with debugging info327- **Input Validation**: All inputs validated with Zod schemas328- **HTTPS Support**: Secure communication with Weblate instances329330## 🤝 Contributing331332We welcome contributions! Please see our [Contributing Guidelines](./docs/DEVELOPMENT.md#contributing):3333341. **Fork** the repository3352. **Create** a feature branch from main3363. **Implement** changes with tests3374. **Update** documentation3385. **Submit** a pull request339340### Code Style341- Use TypeScript for type safety342- Follow NestJS conventions343- Add comprehensive tests344- Update documentation345346## 📄 License347348MIT License - see [LICENSE](./LICENSE) file for details.349350## 🙏 Acknowledgments351352- **Weblate**: For providing an excellent translation management platform353- **Model Context Protocol**: For the standardized protocol specification354- **NestJS**: For the robust application framework355- **Contributors**: Everyone who helps improve this project356357---358359**Built with ❤️ for the translation community**360361*Need help? Check our [documentation](./docs/) or create an [issue](https://github.com/mmntm/weblate-mcp/issues)!*
Full transparency — inspect the skill content before installing.