Mobile Server

---

What is this?

MCP Mobile Server is a Model Context Protocol server that gives AI assistants direct, structured access to your mobile development toolchain. It bridges Claude Desktop (and other MCP clients) to Flutter, Android SDK, and iOS/Xcode workflows through 36 typed tools and 10 high-level "super-tools" that orchestrate complete multi-step workflows.

Instead of switching between terminals and docs, you describe what you want in natural language and the server executes the right commands — with validation, error handling, and fallback strategies built in.

Supported platforms: Android · iOS · Flutter · macOS · Linux · Windows (partial)

---

Features

Category	Tools	What you can do
Core / Health	5	Environment diagnostics, Flutter doctor, device discovery
Device Management	9	List, create, start, and stop Android emulators and iOS simulators
Flutter Development	6	Hot reload sessions, builds, tests, dependency management
Utilities	4	Logcat, screenshots, simulator boot/shutdown
Setup & Configuration	2	Automated Flutter and Android SDK environment setup
Super-Tools (workflows)	10	Complete end-to-end workflows combining multiple atomic tools

Super-Tools — complete workflows in one call

Tool	What it does
flutter_dev_session	Selects best available device, runs doctor, starts hot reload — one command
flutter_test_suite	Unit + widget + integration tests with coverage reporting
flutter_release_build	Multi-platform release builds (APK, App Bundle, IPA)
flutter_deploy_pipeline	End-to-end: test → build → sign
flutter_fix_common_issues	Diagnoses and auto-fixes common Flutter build errors
flutter_inspector_session	Widget inspection session
mobile_device_manager	Intelligent device orchestration across platforms
android_full_debug	Device selection → APK install → launch → logcat in one step
android_emulator_workflow	AVD create → start → wait → ready
ios_simulator_manager	Boot → wait → ready → screenshot lifecycle management

Security built in

• All shell commands are validated against an allowlist before execution
• Dangerous pattern detection blocks injection attempts
• Path traversal protection on all file arguments
• Runtime input validation via Zod
• Configurable timeouts on long-running processes

---

Requirements

Requirement	Version
Node.js	18.0.0 or later
npm or yarn	any recent version
Flutter SDK	3.0+ (for Flutter tools)
Android SDK / Android Studio	any recent (for Android tools)
Xcode	14+ on macOS (for iOS tools)

You only need the SDKs for the platforms you work on. The server starts and serves tools even when some SDKs are absent.

---

Installation

Option 1 — Run with npx (no install needed)

npx @cristianoaredes/mcp-mobile-server

Option 2 — Install globally

npm install -g @cristianoaredes/mcp-mobile-server
mcp-mobile-server

Option 3 — Build from source

git clone https://github.com/cristianoaredes/mcp-mobile-server.git
cd mcp-mobile-server
npm install
npm run build
npm start

---

Claude Desktop Setup

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

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

Restart Claude Desktop after saving. The 36 mobile development tools will appear automatically.

---

Usage Examples

Check your environment

Use the health_check tool to verify the mobile development server is working

Run flutter_doctor to check my Flutter setup

Work with devices

List all connected Android devices and iOS simulators

Start a Flutter development session with hot reload on the best available device

Build and test

Run the full test suite for my Flutter project at /path/to/project

Build release versions for Android and iOS

Fix build problems

My Flutter app won't build. Use flutter_fix_common_issues to diagnose and fix it.

Validate the installation from the command line

# After building from source:
npm run mcp:validate

# Expected output:
# ✅ Server configuration is valid
# ✅ 36 tools registered

---

Project Structure

src/
  server.ts          # MCP server entry point
  tools/
    android.ts       # Android SDK tools
    ios.ts           # iOS / Xcode / Simulator tools
    flutter.ts       # Flutter SDK tools
    super-tools.ts   # High-level workflow automation
    setup-tools.ts   # Environment setup tools
  utils/
    process.ts       # Process execution and tracking
    security.ts      # Command validation and sandboxing
    fallbacks.ts     # Fallback strategies (ADB → native-run, etc.)
    tool-categories.ts # Tool registry

The server communicates over stdio using JSON-RPC 2.0, the standard MCP transport.

---

Contributing

# Clone and install
git clone https://github.com/cristianoaredes/mcp-mobile-server.git
cd mcp-mobile-server
npm install

# Run in development mode (watch)
npm run dev

# Run tests
npm test

# Run linter and full CI check
npm run ci

See CONTRIBUTING.md for guidelines and docs/ for the full documentation set.

---

Documentation

Resource	Description
Quick Start Guide	Get running in under 5 minutes
Tools Reference	All 36 tools with parameters and examples
Architecture	System design, security layer, and ADRs
Android Workflow	Android development guide
iOS Workflow	iOS development guide
Flutter Workflow	Flutter development guide
Troubleshooting	Common issues and solutions

---

Troubleshooting

Flutter not found

# Run the automated setup tool
# In Claude Desktop: "Use flutter_setup_environment to install Flutter"

Android SDK not configured

# In Claude Desktop: "Use android_sdk_setup to configure Android"

No devices available

# List what's available
# "Use android_list_emulators and ios_list_simulators to see available devices"

# Or start a new one
# "Use android_start_emulator to launch an Android emulator"

Claude Desktop not recognizing the server

1. Verify the config file path is correct for your OS
2. Check the JSON is valid (no trailing commas)
3. Restart Claude Desktop completely
4. Ask Claude: "Use health_check to verify the mobile server"

---

License

MIT — free to use, modify, and distribute.

---