🚀 MCP Mobile Server

🌟 Why MCP Mobile Server?

MCP Mobile Server transforms your AI assistant into a mobile development powerhouse. Whether you're building with Flutter, developing for iOS, or creating Android apps, this server provides seamless integration with Claude Desktop, Windsurf, and other MCP-compatible clients.

✨ Key Features

🎯 Intelligent Automation

• Smart device selection and management

• Automated environment setup

• Self-healing build processes

• Intelligent error resolution

⚡ Developer Productivity

• Hot reload development sessions

• One-command deployments

• Parallel testing across devices

• Automated dependency management

🔧 Complete Toolchain

• Flutter, Android, and iOS tools

• Emulator and simulator control

• Build and test automation

• Performance profiling

🤖 AI-First Design

• Built for Claude Desktop

• Natural language commands

• Context-aware suggestions

• Workflow optimization

🚀 Quick Start

Installation

# Install globally
npm install -g @cristianoaredes/mcp-mobile-server

# Or run directly with npx
npx @cristianoaredes/mcp-mobile-server

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mobile-dev": {
      "command": "npx",
      "args": ["@cristianoaredes/mcp-mobile-server"]
    }
  }
}

First Steps

# Check your environment
mcp-mobile-server health_check

# Setup Flutter automatically
mcp-mobile-server flutter_setup_environment --action=full

# Start developing
mcp-mobile-server flutter_dev_session --cwd=/path/to/project

🛠️ Available Tools

🚀 Super Tools - Complete Workflows

These intelligent tools combine multiple operations for maximum productivity:

🔧 Core Tools (5)

• health_check - System diagnostics and environment validation

• flutter_doctor - Flutter environment verification

• flutter_version - SDK version management

• flutter_list_devices - Device discovery

• android_list_devices - Android device detection

📱 Device Management (9)

• native_run_list_devices - Universal device listing

• native_run_install_app - Cross-platform app installation

• ios_list_simulators - iOS simulator discovery

• android_list_emulators - AVD management

• android_create_avd - Virtual device creation

• android_start_emulator - Emulator lifecycle

• android_stop_emulator - Resource management

• ios_shutdown_simulator - iOS cleanup

• flutter_launch_emulator - Quick emulator start

⚡ Development (6)

• flutter_run - Hot reload server

• flutter_build - Production builds

• flutter_test - Test runner

• flutter_clean - Cache management

• flutter_pub_get - Dependencies

• android_install_apk - APK deployment

🛠️ Utilities (4)

• android_logcat - Debug logging

• android_screenshot - Screen capture

• ios_boot_simulator - iOS startup

• ios_take_screenshot - iOS capture

🔧 Setup Tools (2)

• flutter_setup_environment - Automated Flutter setup

• android_sdk_setup - Android SDK configuration

🚀 Advanced Workflows (10)

• flutter_performance_profile - Performance analysis

• flutter_deploy_pipeline - Full deployment

• android_full_debug - Complete debugging

• ios_simulator_manager - iOS orchestration

• flutter_inspector_session - Widget inspection

💡 Real-World Examples

Example 1: Start a Flutter Project

// Claude Desktop conversation
User: "Create a new Flutter app and run it"
Claude: I'll create a new Flutter app and start the development server.

// Behind the scenes:
flutter_create({ name: "my_app", org: "com.example" })
flutter_dev_session({ cwd: "./my_app", preferPhysical: true })

Example 2: Fix Build Errors

// Automatic error resolution
User: "My Flutter app won't build"
Claude: Let me diagnose and fix the build issues.

// Executes:
flutter_fix_common_issues({ cwd: ".", deep: true })

Example 3: Deploy to Multiple Platforms

// One-command deployment
User: "Build release versions for Android and iOS"
Claude: I'll create optimized release builds for both platforms.

// Runs:
flutter_release_build({ 
  cwd: ".",
  platforms: ["apk", "appbundle", "ipa"],
  obfuscate: true
})

🏗️ Architecture

graph TD
    A[Claude Desktop / MCP Client] -->|JSON-RPC| B[MCP Mobile Server]
    B --> C[Tool Registry]
    B --> D[Process Manager]
    B --> E[Security Layer]
    
    C --> F[Flutter Tools]
    C --> G[Android Tools]
    C --> H[iOS Tools]
    C --> I[Super Tools]
    
    F --> J[Flutter SDK]
    G --> K[Android SDK]
    H --> L[Xcode]

Design Principles

• 🔒 Security First: All commands validated and sandboxed

• ⚡ Performance: Parallel execution and intelligent caching

• 🎯 Reliability: Automatic retries and fallback strategies

• 📦 Modular: Extensible plugin architecture

• 🌍 Cross-Platform: Works on macOS, Linux, and Windows

📋 Requirements

Minimum Requirements

• Node.js 18.0+

• npm or yarn

• One of: Flutter, Android SDK, or Xcode

Recommended Setup

• Flutter 3.0+ for Flutter development

• Android Studio or Android SDK for Android

• Xcode 14+ for iOS (macOS only)

• VS Code with Flutter extension

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/cristianoaredes/mcp-mobile-server.git

# Install dependencies
cd mcp-mobile-server
npm install

# Run in development mode
npm run dev

# Run tests
npm test

📚 Documentation

🐛 Troubleshooting

Flutter not found

# Run the setup tool
mcp-mobile-server flutter_setup_environment --action=full

Android SDK not configured

# Configure Android environment
mcp-mobile-server android_sdk_setup --action=configure

Permission denied errors

# Check permissions
ls -la $(which mcp-mobile-server)
chmod +x $(which mcp-mobile-server)

📊 Project Status

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Model Context Protocol by Anthropic

• Flutter team for the amazing framework

• All contributors and users of this project

🌟 Support the Project

If you find this useful, please consider:

Built with ❤️ for the mobile development community

Report Bug • Request Feature • Documentation