A comprehensive Model Context Protocol (MCP) server that provides AI agents with enterprise-grade access to Kotlin-based Android development projects. This server enables context-aware assistance with advanced security, privacy compliance, AI integration, and comprehensive development tools.
🧠 Kotlin MCP Server for Android app development using OpenAI, Gemini, or OpenRouter. Enables AI-assisted coding via Aider, Gradle build/test integration, Kotlin LSP, and Docker-based portability.
2026-10-27
Estrellas
31
Herramientas
—
Disponibilidad
—
📋 Revision History
Version 2.1(Current - August 2025)
Enhanced Release: Unified Intelligent Server
🎯 Latest Improvements
🧠 Intelligent Tool Management: All 27 tools now use intelligent proxy system with LSP-like capabilities
🔄 Server Consolidation: Unified into single kotlin_mcp_server.py with enhanced architecture
📁 Clean Architecture: Archived redundant server versions for cleaner project structure
⚡ Enhanced Tool Exposure: Complete tool suite properly exposed through intelligent management system
🛠️ Improved Tool Routing: Smart delegation between native implementations and intelligent proxies
🔧 Architectural Changes
Unified Server: Single kotlin_mcp_server.py replaces multiple server versions
Intelligent Proxy System: Tools without full implementations use smart proxies with AI enhancement
Clean File Structure: Legacy servers archived in archive/legacy-servers/
Enhanced Tool Manager: Integration with IntelligentMCPToolManager for advanced capabilities
Complete Tool Coverage: All 32 tools properly exposed and functional
✅ Dynamic Configuration: Cross-platform with environment variables
✅ 31 Enhanced Tools: AI-integrated with intelligent error handling
📋 System Requirements
Python 3.8+ (3.9+ recommended)
pip (Python package manager)
Git (for cloning repository)
IDE with MCP support (VS Code, JetBrains IDEs, Claude Desktop)
🔧 Installation Steps
1. Clone Repository
git clone <your-repo-url>
cd kotlin-mcp-server
2. Automated Installation & Configuration
The project includes an enhanced installation script that handles all configuration automatically:
# Interactive installation (recommended for first-time users)
python3 install.py
# Non-interactive installation with specific configuration
python3 install.py [install_type] [project_path] [server_name] [use_env_vars]
# Show all available options
python3 install.py --help
Installation Types:
1 - Portable: Run directly from project directory
2 - System: Install command to PATH (kotlin-android-mcp)
3 - Module: Enable python -m kotlin_mcp_server
Configuration Examples:
# Interactive setup (asks for your preferences)
python3 install.py 1
# Portable with your Android project path (replace with actual path)
python3 install.py 1 ~/AndroidStudioProjects/MyApp
# System installation with dynamic environment variables
python3 install.py 2 none my-android-server true
# Module installation with custom server name
python3 install.py 3 /path/to/project kotlin-dev false
What the installer does:
✅ Installs all Python dependencies from requirements.txt
✅ Creates platform-specific config files (Claude, VS Code, generic)
✅ Sets up proper file permissions for scripts
✅ Configures environment variables based on your choices
✅ Eliminates manual path updates in configuration files
✅ Provides clear integration instructions for your setup
💡 Note: The installation script automatically configures project paths and server settings, so manual environment configuration is only needed for advanced features like AI integration or custom security settings.
# Test the server with your configured setup
# If you used a fixed project path during installation:
python3 kotlin_mcp_server.py
# If you're using dynamic/environment variables:
python3 kotlin_mcp_server.py /path/to/android/project
# For system installation:
kotlin-android-mcp
# For module installation:
python3 -m kotlin_mcp_server
# Validate configuration (optional)
python3 validate_config.py
# Run comprehensive tests (optional)
python test_mcp_comprehensive.py
# Test VS Code bridge server (optional)
python3 vscode_bridge.py &
sleep 2
curl http://localhost:8080/health
# Should return: {"status": "healthy", ...}
kill %1 # Stop background bridge server
⚡ Quick Setup Commands
# Complete setup with one command (interactive)
python3 install.py
# Quick setup for development environment
make setup-dev
# Quick validation
make dev-check
# Full quality pipeline
make ci
# Test VS Code bridge server (optional)
python3 vscode_bridge.py --test-mode
🎯 Installation Summary
The enhanced installation process has eliminated the need for manual configuration:
✅ Before (Manual): Users had to manually edit config files, find paths, update environment variables
✅ After (Automated): One command creates everything ready-to-use
Key Improvements:
🚀 Zero Manual Configuration: No more path updates or variable editing
🎛️ Interactive & Non-Interactive: Works in both modes for all users
🔧 Platform-Specific Configs: Generates optimized files for each IDE/client
📋 Clear Instructions: Provides exact integration steps for your setup
For containerized deployment, the project includes comprehensive Docker support:
Quick Docker Setup
# 1. Validate Docker configuration
python3 validate_docker.py
# 2. Build and run with the setup script
./docker-setup.sh build
./docker-setup.sh start
# 3. Or use Docker Compose directly
docker-compose up -d kotlin-mcp-server
Docker Features
🔒 Security: Non-root user, minimal attack surface
📦 Optimized: Multi-stage builds, layer caching
🔍 Health Checks: Automatic container health monitoring
🛠️ Development: Volume mounts for live development
🚀 Production: Daemon mode for production deployment
Available Commands
./docker-setup.sh build # Build the image
./docker-setup.sh start # Interactive development
./docker-setup.sh daemon [path] # Production daemon mode
./docker-setup.sh logs # View container logs
./docker-setup.sh shell # Open container shell
./docker-setup.sh test # Run tests in container
./docker-setup.sh clean # Clean up resources
Ready to see the system generate complete, production-ready Android apps? Follow these steps to witness the full E2E workflow:
🚀 Quick Start: Generate Your First App
# 1. Build the Kotlin sidecar (creates fat JAR)
make sidecar
# 2. Generate complete Android app with all features
make e2e
# 3. Your APK appears here:
ls -la e2e/sampleapp/app/build/outputs/apk/debug/app-debug.apk
✅ Working Android app with HomeScreen + DetailsScreen
✅ Room database with entities and DAOs
✅ Retrofit network layer with API service
✅ Unit tests that pass (Robolectric + JVM tests)
✅ APK ready to install on device/emulator
🔧 Available Commands
# Build Kotlin sidecar JAR
make sidecar
# Generate complete Android app
make e2e
# Format and optimize code
make fix
# Run detekt static analysis
make detekt
# Run spotless code formatting check
make spotless
# Clean all artifacts
make clean
# Ensure Android SDK is installed and ANDROID_SDK_ROOT is set
export ANDROID_SDK_ROOT=/path/to/android/sdk
# Clean and rebuild
make clean && make e2e
Sidecar connection issues:
# Check if JAR was built
ls -la kotlin-sidecar/build/libs/kotlin-sidecar.jar
# Test sidecar directly
java -jar kotlin-sidecar/build/libs/kotlin-sidecar.jar
APK not generated:
# Check build logs
cd e2e/sampleapp && ./gradlew assembleDebug --info
# Ensure JDK 17 is used
java -version # Should show Java 17
📈 Performance Benchmarks
The system is optimized for:
Sidecar startup: < 2 seconds
Code generation: < 5 seconds per component
Build time: < 30 seconds for debug APK
Test execution: < 10 seconds for unit tests
🎉 Success Indicators
When everything works correctly:
✅ kotlin-sidecar.jar builds successfully
✅ e2e/sampleapp directory created with full project
✅ ./gradlew assembleDebug completes without errors
🎯 The generated app is production-ready and can be opened in Android Studio immediately!
� Migration from V1.0 to V2.0
⚡ Quick Migration Steps
If you have an existing V1.0 installation:
Backup Current Setup:
# Backup your existing configuration
cp mcp_config*.json ~/backup/
Update to V2.0:
# Pull latest changes
git pull origin main
# Run V2.0 installer
python3 install.py 1
Verify Migration:
# Test the new modular architecture
python3 -c "from kotlin_mcp_server import KotlinMCPServer; print('✅ V2.0 Ready!')"
🔍 What's Automatically Migrated
✅ All 30 original tools preserved with enhanced AI capabilities
✅ Configuration files updated with dynamic environment variables
✅ Project paths converted to cross-platform format
✅ Dependencies updated to latest versions
✅ Security settings enhanced with new compliance features
⚠️ Migration Notes
Backward Compatibility: V2.0 maintains full compatibility with V1.0 project structures
Enhanced Output: Code generation now produces complete implementations instead of templates
New Environment Variables: Optional new configuration options (see .env.example)
Modular Structure: Internal architecture improved (no user action needed)
🏗️ Project Root Resolution Policy
Overview
All tools in the Kotlin MCP Server have been refactored to work exclusively on the user's project workspace, never on the MCP server's current working directory. This ensures safe, predictable tool behavior and prevents accidental modifications outside your project.
Path Resolution Priority
Tools resolve the project root in this order:
Explicit Input: project_root or projectRoot parameter
Environment Variables: PROJECT_PATH or WORKSPACE_PATH
IDE Metadata: Workspace root from MCP client (VS Code, Cursor, etc.)
Fail-Safe: Tools will error rather than use server CWD
Input Synonyms
Tools accept both camelCase and snake_case parameter names:
Queries local or remote language models for code assistance.
{
"name": "query_llm",
"arguments": {
"prompt": "Generate a Kotlin data class for User with validation",
"llm_provider": "local",
"model": "codellama",
"privacy_mode": true,
"max_tokens": 1000,
"temperature": 0.2
}
}
Implement proper compliance features from the start
Use secure storage for API keys and secrets
Enable audit logging for compliance requirements
Performance Optimization
Use parallel: true for Gradle builds when possible
Generate tests incrementally rather than all at once
Use local LLM providers for privacy-sensitive code analysis
Enable caching for API setups
Error Handling
All tools provide comprehensive error information:
{
"success": false,
"error": "File already exists",
"details": {
"file_path": "src/main/kotlin/User.kt",
"suggestion": "Use a different file name or set overwrite: true"
}
}
{
"name": "query_llm",
"arguments": {
"prompt": "Generate a Kotlin data class for User with validation",
"llm_provider": "local",
"privacy_mode": true,
"max_tokens": 1000
}
}
# Build and run with Docker
docker-compose up -d
# Or build manually
docker build -t kotlin-mcp-server .
docker run -p 8000:8000 -v $(pwd):/workspace kotlin-mcp-server
AI Agent Integration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
Black Formatter (ms-python.black-formatter) - Code formatting
isort (ms-python.isort) - Import sorting
Jupyter (ms-toolsai.jupyter) - Notebook support (optional)
MCP for VS Code - Model Context Protocol support (if available)
JetBrains IDEs (IntelliJ IDEA, Android Studio)
Required Plugins:
Python Plugin - For Python script execution
MCP Plugin - Model Context Protocol support (check JetBrains marketplace)
Kotlin Plugin - Built-in for Android Studio, install for IntelliJ
Android Plugin - Built-in for Android Studio
Claude Desktop Integration
No additional plugins required - uses built-in MCP support.
🛠️ IDE Configuration
Visual Studio Code
Install Python Extension Pack:
code --install-extension ms-python.python
Configure MCP Server:
The installation script generates mcp_config_vscode.json with the correct paths. Simply add to VS Code settings.json (Cmd/Ctrl + Shift + P → "Preferences: Open Settings (JSON)"):
Configuration Content:
Simply copy the content from the generated mcp_config_claude.json file to your Claude Desktop configuration file. The installation script has already configured all paths and settings correctly.
// In your VS Code extension
const response = await fetch('http://localhost:8080/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
tool: 'analyze_project',
arguments: { analysis_type: 'architecture' }
})
});
const result = await response.json();
5. Configuration:
# Environment variables for bridge server
MCP_BRIDGE_HOST=localhost # Server host
MCP_BRIDGE_PORT=8080 # Server port
VSCODE_WORKSPACE_FOLDER=/path # Override workspace detection
Other IDEs
For IDEs with MCP support:
Vim/Neovim: Use coc-mcp or similar MCP plugins
Emacs: Install mcp-mode package
Sublime Text: Install MCP package via Package Control
�️ Troubleshooting
Common Installation Issues
Python Version Compatibility
# Check Python version (must be 3.8+)
python3 --version
# If using older Python, install newer version
# macOS with Homebrew:
brew install [email protected]
# Ubuntu/Debian:
sudo apt update && sudo apt install python3.11
Dependency Installation Errors
# Upgrade pip first
python3 -m pip install --upgrade pip
# Install with verbose output for debugging
pip install -r requirements.txt -v
# Use alternative index if needed
pip install -r requirements.txt -i https://pypi.org/simple/
Most configuration issues are now resolved automatically:
# Regenerate configuration with the enhanced installer
python3 install.py
# For specific setup types:
python3 install.py 1 /your/android/project my-server false
python3 install.py --help # See all options
Legacy Manual Configuration Issues
If you're still using manual configuration from older versions:
# 1. Update to the new installer (recommended)
python3 install.py
# 2. Or manually find your actual paths (legacy method)
cd /path/to/kotlin-mcp-server && pwd
cd /path/to/android/project && pwd
# 3. Update config files - replace ${MCP_SERVER_DIR} with actual path
# Example: Change this
"cwd": "${MCP_SERVER_DIR}"
# To this (your actual path)
"cwd": "~/Documents/kotlin-mcp-server"
💡 Pro Tip: The new installer eliminates these manual steps entirely!
Environment Variable Issues
# Check if variables are set
env | grep MCP
env | grep WORKSPACE
# Load environment file manually if needed
source .env
# Test variable expansion
echo $MCP_SERVER_DIR
echo $WORKSPACE_PATH
MCP Server Not Starting
Check configuration file paths in your IDE settings
# Test bridge server is running
curl http://localhost:8080/health
# Check if port is in use
netstat -an | grep 8080
lsof -i :8080
# Start bridge server with debug
MCP_BRIDGE_HOST=0.0.0.0 MCP_BRIDGE_PORT=8080 python3 vscode_bridge.py
# Test specific tool call
curl -X POST http://localhost:8080/ \
-H "Content-Type: application/json" \
-d '{"tool": "list_tools", "arguments": {}}'
# Common fixes:
# 1. Check firewall settings for port 8080
# 2. Ensure python3 vscode_bridge.py is running
# 3. Verify VSCODE_WORKSPACE_FOLDER environment variable
# 4. Check bridge server logs for errors
Permission Errors
# macOS/Linux: Fix permissions
chmod +x *.py
chmod 755 servers/mcp-process/
# Windows: Run as administrator or check file permissions
Runtime Issues
AI Integration Failures
# Test local LLM connection
curl http://localhost:11434/api/generate -d '{"model":"llama2","prompt":"test"}'
# Verify API keys are set
python3 -c "import os; print('OpenAI key:', os.getenv('OPENAI_API_KEY', 'Not set'))"
File Operation Errors
# Check disk space
df -h
# Verify write permissions
touch test_file.txt && rm test_file.txt
# Check workspace path
ls -la "${WORKSPACE_PATH}"
Check Logs: Look in mcp_security.log for detailed error information
Run Diagnostics: Use python3 comprehensive_test.py --verbose
Validate Configuration: Run python3 breaking_change_monitor.py
Test Individual Components:
# Test core server
python3 kotlin_mcp_server.py --test
# Test enhanced features
python3 kotlin_mcp_server.py --test
# Test AI integration
python3 kotlin_mcp_server.py --test
Contact Support: Include logs, system info, and error messages when reporting issues
🌉 VS Code Bridge Server
The VS Code Bridge Server provides HTTP API access to MCP tools for VS Code extensions and other applications that can't directly use the MCP protocol.
When to Use the Bridge Server
VS Code Extensions: When building custom VS Code extensions that need MCP functionality
HTTP Clients: When integrating with tools that only support HTTP APIs
Remote Access: When you need to access MCP tools from another machine
Testing: For easy testing of MCP tools using curl or Postman
Web Applications: For web-based interfaces to MCP functionality
Bridge Server Features
Workspace Detection
Automatically detects current VS Code workspace
Uses VSCODE_WORKSPACE_FOLDER environment variable
Falls back to current working directory
Available Endpoints
Health Check:
GET /health
# Returns: server status, workspace info, available tools
# Bridge server configuration
MCP_BRIDGE_HOST=localhost # Server host (default: localhost)
MCP_BRIDGE_PORT=8080 # Server port (default: 8080)
# Workspace configuration
VSCODE_WORKSPACE_FOLDER=/path/to/project # Override workspace detection
PROJECT_PATH=/path/to/project # Fallback project path
Security Considerations
# For remote access (use with caution)
MCP_BRIDGE_HOST=0.0.0.0 # Allow external connections
# For local development only (recommended)
MCP_BRIDGE_HOST=127.0.0.1 # Local connections only
# Port already in use
netstat -tulpn | grep 8080
# Kill process using port: sudo kill -9 <PID>
# Permission denied
sudo ufw allow 8080 # Ubuntu
sudo firewall-cmd --add-port=8080/tcp # CentOS
# Connection refused
# Check if server is running:
ps aux | grep vscode_bridge.py
# Test with verbose curl:
curl -v http://localhost:8080/health
Lightweight: Minimal HTTP server with low memory footprint
Workspace-aware: Automatically uses current VS Code workspace
Error handling: Graceful error responses with details
CORS support: Includes CORS headers for web applications
🧪 Testing & Quality Assurance
This project includes a comprehensive testing and quality assurance system. For detailed testing information, see TESTING_GUIDE.md.
Quick Testing Commands
# Run all tests
make test
# Run tests with coverage
make coverage
# Run quality checks
make lint
# Full CI pipeline
make ci
# Check for breaking changes
python breaking_change_monitor.py
🧠 Kotlin MCP Server for Android app development using OpenAI, Gemini, or OpenRouter. Enables AI-assisted coding via Aider, Gradle build/test integration, Kotlin LSP, and Docker-based portability.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Kotlin?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Kotlin necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Kotlin?
Kotlin se ejecuta localmente por stdio.
¿Cuándo se comprobó Kotlin por última vez?
Última comprobación: 2026-10-27. 🧠 Kotlin MCP Server for Android app development using OpenAI, Gemini, or OpenRouter. Enables AI-assisted coding via Aider, Gradle build/test integration, Kotlin LSP, and Docker-based portability.