Sinhala MCP
MCP server that translates Sinhala/Singlish instructions into precise English technical specifications using Google Gemini AI.
Installation
npx sinhala-mcpAsk AI about Sinhala MCP
Powered by Claude Β· Grounded in docs
I know everything about Sinhala MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π±π° sinhala-mcp
π Sri Lanka's First AI-Powered MCP Server for Sinhala Developers
Break the language barrier. Code in your mother tongue.
A production-ready Model Context Protocol server that translates Sinhala/Singlish instructions into precise English technical specifications using Google Gemini AI.
Note (v0.1.8+): Previous versions of this README documented incorrect configuration methods that resulted in silent failures. The methods below have been tested and verified. If you previously configured sinhala-mcp using the old instructions, remove the old config and follow the updated steps below.
Why sinhala-mcp?
As the first of its kind in Sri Lanka, sinhala-mcp empowers Sinhala-speaking developers to:
- Code naturally in your preferred language (Sinhala or Singlish)
- Get precise technical translations optimized for AI coding agents
- Boost productivity by removing language friction from development workflows
- Stay ahead with cutting-edge AI integration via Google's Gemini
Features
- Sinhala/Singlish Translation: Convert colloquial commands into structured English technical specifications
- Context-Aware: Automatically infers technical context (e.g., "Login" β "Authentication flow")
- Environment Variable Auth: Secure API key management via environment variables
- Production-Ready: Comprehensive error handling, retry logic, timeout protection, input validation, and health checks
- MCP Compliant: Works with Claude Desktop, VS Code, Claude Code CLI, and other MCP-compatible tools
- Latest AI: Uses Google GenAI SDK with Gemini models (supports 1.5-flash, 2.5-flash, 2.5-flash-lite, 2.5-pro)
Installation
pip install sinhala-mcp
Or with uv:
uv pip install sinhala-mcp
Manual Installation from Source
If you encounter issues with PyPI installation:
git clone https://github.com/Thamindu-Dev/sinhala-mcp.git
cd sinhala-mcp
pip install -e .
Verifying Installation
After installing, verify the server is accessible:
sinhala-mcp --help
If this returns a help message, the package is installed correctly and available on your PATH.
Windows users: If
sinhala-mcpis not found, the Python Scripts directory may not be on your PATH. The executable is located atC:\Users\<you>\AppData\Local\Programs\Python\PythonXX\Scripts\sinhala-mcp.exewhereXXis your Python version (e.g.,Python313). See Troubleshooting for details.
Configuration
Step 1: Get a Google Gemini API Key
- Visit Google AI Studio
- Create a new API key
- Keep it secure β never commit it to version control
Step 2: Configure Your MCP Client
IMPORTANT: The server reads the API key from the GEMINI_API_KEY environment variable. Without this key, the server will silently fail to connect β you will see "Failed to reconnect" in your MCP client, not a clear error message.
Method 1: Claude Code CLI (Recommended)
The fastest way to add sinhala-mcp to Claude Code:
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-api-key-here -- sinhala-mcp
With a specific Gemini model:
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -e GEMINI_MODEL=gemini-2.5-flash-lite -- sinhala-mcp
What this does: Writes the server config to ~/.claude.json under the mcpServers key. This is the correct config file for Claude Code β do NOT use ~/.claude/settings.json (it does not support MCP servers) or ~/.claude/.mcp.json.
To verify it was added:
claude mcp list
To remove it later:
claude mcp remove sinhala-mcp
Manual Claude Code Config
If you prefer to edit the config file directly:
macOS/Linux: ~/.claude.json
Windows: %USERPROFILE%\.claude.json
Add under the "mcpServers" key:
{
"mcpServers": {
"sinhala-mcp": {
"type": "stdio",
"command": "sinhala-mcp",
"args": [],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
Windows users: If
sinhala-mcpis not on PATH, use the full path:"command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\sinhala-mcp.exe"Replace
<you>with your Windows username andPython313with your installed Python version.
Project-Specific Config
To add sinhala-mcp for a specific project only, navigate to the project directory and run:
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -s project -- sinhala-mcp
Or add it manually to the project entry in ~/.claude.json under "<project-path>" β "mcpServers".
Method 2: Claude Desktop
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Roaming\Claude\claude_desktop_config.json
{
"mcpServers": {
"sinhala-mcp": {
"type": "stdio",
"command": "sinhala-mcp",
"args": [],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
Optional: Override the default model by adding "GEMINI_MODEL": "gemini-2.5-flash-lite" to env.
Method 3: VS Code MCP Extension
Create or update .vscode/settings.json:
{
"mcp.servers": {
"sinhala-mcp": {
"command": "sinhala-mcp",
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}
For advanced configuration with model sampling, create .vscode/mcp.json:
{
"servers": {
"sinhala-mcp": {
"command": "uvx",
"args": ["sinhala-mcp"],
"env": {
"GEMINI_API_KEY": "${input:gemini_api_key}",
"GEMINI_MODEL": "${input:gemini_model}"
},
"type": "stdio"
}
},
"inputs": [
{
"id": "gemini_api_key",
"type": "promptString",
"description": "Google Gemini API Key",
"default": ""
},
{
"id": "gemini_model",
"type": "promptString",
"description": "Gemini Model (optional)",
"default": "gemini-2.5-flash"
}
]
}
Then update .vscode/settings.json for model sampling:
{
"chat.mcp.serverSampling": {
"sinhala-mcp/.vscode/mcp.json: sinhala-mcp": {
"allowedModels": [
"copilot/auto",
"gemini-1.5-flash",
"gemini-2.5-flash",
"gemini-2.5-flash-lite",
"gemini-2.5-pro"
]
}
}
}
Available Tools
translate_sinhala_instruction
Translates Sinhala or Singlish instructions into precise English technical prompts.
Usage:
Use translate_sinhala_instruction to translate "mata login form ekak hadanna one"
Parameters:
instruction(string, required): The Sinhala or Singlish instruction (max 5000 characters)
Example Output:
Original (Sinhala/Singlish):
mata login page ekak hadanna one
Translated (English Technical Prompt):
Implement a user authentication system with login functionality including:
- Username/email and password input fields
- Form validation for credentials
- Authentication endpoint integration
- Session management after successful login
- Error handling for failed authentication attempts
health_check
Check if the MCP server and Gemini API connection are working.
Usage:
Run health_check
Usage Examples
Web Development
Input: "Mata dashboard ekak denna user stats display karanna" Output:
Create a user analytics dashboard with:
- Real-time user statistics display
- Data visualization charts
- Filtering and search capabilities
- Responsive layout for mobile/desktop
- Authentication-protected access
Backend Development
Input: "Database eka connect karanna API endpoint ekak hadala denna" Output:
Implement database integration with REST API:
- Set up database connection pool
- Create CRUD endpoints for data access
- Implement proper error handling
- Add data validation and sanitization
- Include authentication/authorization middleware
Frontend Features
Input: "Profile page eke photo upload eka hadanna" Output:
Implement profile photo upload feature:
- File upload input with image type validation
- Client-side image preview
- Size and format restrictions
- Upload progress indicator
- Server-side file storage integration
- Error handling for upload failures
Development
# Clone the repository
git clone https://github.com/Thamindu-Dev/sinhala-mcp.git
cd sinhala-mcp
# Install in editable mode
pip install -e .
# Test server
python test_simple.py
Project Structure
sinhala-mcp/
βββ src/
β βββ sinhala_mcp/
β βββ __init__.py
β βββ server.py # Main MCP server implementation
βββ pyproject.toml # Package configuration
βββ README.md
βββ LICENSE
Security
- API keys stored in environment variables only
- No local file storage of credentials
- Input validation and sanitization
- Protection against injection attacks
- Rate limit handling
- Open source β fully auditable
Technical Specifications
- Build Backend: hatchling
- Python Version: 3.10+ (tested on 3.10-3.13)
- Dependencies:
mcp>=0.9.0,google-genai>=1.0.0,google-api-core>=1.0.0 - Default Model:
gemini-2.5-flash - Supported Models:
gemini-2.5-flash,gemini-2.5-flash-lite,gemini-2.5-pro,gemini-1.5-flash - Max Instruction Length: 5000 characters
- API Timeout: 30 seconds
- Retry Logic: 2 retries with exponential backoff
Troubleshooting
"Failed to reconnect" in Claude Code / Claude Desktop
This is the most common issue and has two root causes:
- Missing
GEMINI_API_KEY: The server silently fails to start without the API key. You won't see a clear error β just "Failed to reconnect". - Stale Python path (Windows): If you upgraded Python, the
commandpath in your config points to the old version (e.g.,Python310instead ofPython313). The executable no longer exists at the old path, so the server can't start. This was the primary issue reported by users β the old documentation did not account for Python version path changes on Windows.
Fix: Ensure both the API key and the correct executable path are set:
{
"mcpServers": {
"sinhala-mcp": {
"type": "stdio",
"command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\sinhala-mcp.exe",
"args": [],
"env": {
"GEMINI_API_KEY": "your-actual-key-here"
}
}
}
}
Windows: Always verify the path exists. Run
where sinhala-mcpin terminal to find the correct path. If you upgraded Python, the old path won't work β see Python version path changes below.
After updating the config, restart Claude Code / Claude Desktop.
"sinhala-mcp" command not found
Cause: The Python Scripts directory is not on your system PATH, or the package was installed under a different Python version.
Fix (Windows): Use the full path to the executable:
C:\Users\<you>\AppData\Local\Programs\Python\PythonXX\Scripts\sinhala-mcp.exe
Replace <you> with your username and XX with your Python version folder (e.g., Python313).
Fix (macOS/Linux): Find the executable path:
which sinhala-mcp
# or
python -c "import shutil; print(shutil.which('sinhala-mcp'))"
Use the full path in your MCP config if needed.
Python version path changes (Windows)
This is the #1 cause of "Failed to reconnect" on Windows.
When you upgrade Python (e.g., 3.10 β 3.13), pip installs packages into the new version's Scripts directory. The old executable path becomes invalid:
Python 3.10: C:\...\Python310\Scripts\sinhala-mcp.exe
Python 3.13: C:\...\Python313\Scripts\sinhala-mcp.exe
If your MCP config points to the old path, the server won't start. Reinstall the package on the new Python version and update the path in your config:
# Reinstall on new Python
pip install sinhala-mcp
# Update config with new path
claude mcp remove sinhala-mcp
claude mcp add sinhala-mcp -e GEMINI_API_KEY=your-key -- "C:\Users\<you>\AppData\Local\Programs\Python\Python313\Scripts\sinhala-mcp.exe"
VS Code Compatibility Issues
- Some VS Code MCP extensions have model validation restrictions
- Workaround: Set
GEMINI_MODEL=gemini-1.5-flashin your configuration for better compatibility - Important: After changing
GEMINI_MODEL, restart your MCP client for changes to take effect - Alternative: Use Claude Desktop or Claude Code CLI for better compatibility
Model Changes Not Taking Effect
- Issue: Setting
GEMINI_MODELdoesn't change the model being used - Solution: Restart your MCP client (Claude Desktop, VS Code) after modifying environment variables
- Verify: Check MCP server logs for "Using Gemini model: ..." message on startup
Translation Issues
- The model may block content due to safety settings
- Try rephrasing the instruction
Wrong config file location (Claude Code)
Claude Code reads MCP servers from ~/.claude.json (the "mcpServers" key at the top level), not from:
~/.claude/settings.jsonβ this file only holds settings like env vars and plugins, not MCP servers~/.claude/.mcp.jsonβ this is not a valid Claude Code config location.claude/settings.local.jsonβ this only holds per-project permissions
Use claude mcp add to add servers correctly, or edit ~/.claude.json directly.
Support
- Report Issues: GitHub Issues
- MCP Protocol: modelcontextprotocol.io
Contributing
Contributions are welcome! Fork the repository, create a feature branch, and submit a Pull Request.
License
MIT License β see LICENSE for details.
About the Developer
sinhala-mcp was created by Thamindu Hatharasinghe β a passionate Sri Lankan developer dedicated to breaking language barriers in technology.
As Sri Lanka's first Sinhala-to-English technical translation tool for developers, this project represents a milestone in making AI-assisted development accessible to Sinhala-speaking developers worldwide.
- Portfolio: www.thamindu.zynthlab.com
- GitHub: Thamindu-Dev
Made in Sri Lanka, for Sinhala developers worldwide
