Weblate MCP - MCP Server

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

🛠️ 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!