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

Related MCP server: MCP Server Fetch Python

🎯 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):

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

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