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: ``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" } } } } ``

Manual testing: ```bash

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): ``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: ``json { "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 documentation or create an issue!

weblate-mcp