Specter MCP

KMM Diagnostic & Execution Engine

An MCP server providing "hands and eyes" for AI agents working with Kotlin Multiplatform Mobile projects.

---

What is Specter MCP?

Specter MCP enables AI agents (Claude, GPT, etc.) to build, test, debug, and interact with Android and iOS applications through the Model Context Protocol. Think of it as giving your AI assistant the ability to:

- Build and deploy your mobile apps
- Take screenshots and interact with UI elements
- Run unit tests and E2E tests (Maestro)
- Analyze crash logs and debug issues
- Inspect app state (preferences, databases, logs)

Prerequisites

| Requirement | Version | Verify Command |
|-------------|---------|----------------|
| Node.js | 20+ | node --version |
| Android SDK | Any | adb --version |
| Xcode CLI (macOS) | Any | xcrun --version |
| Maestro (optional) | Any | maestro --version |

$3

``bash


Android SDK (if not installed via Android Studio)

export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools"

iOS (macOS only)

xcode-select --install
sudo xcodebuild -license accept

Maestro (optional, for E2E testing)

curl -Ls "https://get.maestro.mobile.dev" | bash
`

Installation

$3

`bash
npm install -g specter-mcp
`

$3

`bash
git clone https://github.com/abd3lraouf/specter-mcp.git
cd specter-mcp
npm install && npm run build
`

Configuration

$3

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

`json
{
"mcpServers": {
"specter-mcp": {
"command": "specter-mcp"
}
}
}
`

$3

Add to your project's .mcp.json:

`json
{
"mcpServers": {
"specter-mcp": {
"command": "specter-mcp"
}
}
}
`

$3

`json
{
"mcpServers": {
"specter-mcp": {
"command": "specter-mcp",
"env": {
"SPECTER_DEBUG": "true",
"ANDROID_SDK_ROOT": "/path/to/android/sdk"
}
}
}
}
`

$3

`json
{
"mcpServers": {
"specter-mcp": {
"command": "node",
"args": ["/absolute/path/to/specter-mcp/dist/index.js"]
}
}
}
`

Available Tools (15)

| Category | Tool | Description |
|----------|------|-------------|
| Build | build_app | Build Android/iOS app (debug/release) |
| | install_app | Install APK or .app on device |
| | launch_app | Launch installed app |
| UI | get_ui_context | Screenshot + UI hierarchy |
| | interact_with_ui | Tap, swipe, input text |
| Testing | run_unit_tests | Run unit tests |
| | run_maestro_flow | Run Maestro E2E flows |
| | run_linter | Detekt, SwiftLint, ktlint |
| Environment | list_devices | List emulators/simulators |
| | manage_env | Boot/shutdown devices |
| | clean_project | Clean build caches |
| Debug | analyze_crash | Parse crash logs, symbolicate |
| | inspect_logs | Filter device logs |
| | inspect_app_state | Read prefs, databases |
| Navigation | deep_link_navigate | Open deep links |

Usage Examples

$3

`
You: Build my Android app in debug mode and install it

Claude: I'll build and deploy your app.
→ build_app(platform: "android", variant: "debug")
→ install_app(platform: "android", appPath: "...")
→ launch_app(platform: "android", appId: "com.example.app")
`

$3

`
You: My iOS app crashed, help me debug it

Claude: Let me analyze the crash.
→ analyze_crash(platform: "ios", appId: "com.example.app")
→ inspect_logs(platform: "ios", minLevel: "error")
`

$3

`
You: Take a screenshot and tap the login button

Claude: I'll capture the UI and interact with it.
→ get_ui_context(platform: "android")
→ interact_with_ui(platform: "android", action: "tap", element: "Login")
`

$3

`
You: Run my login flow test on both platforms

Claude: Running Maestro flows.
→ run_maestro_flow(platform: "android", flowPath: "./maestro/login.yaml")
→ run_maestro_flow(platform: "ios", flowPath: "./maestro/login.yaml")
`

Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| SPECTER_DEBUG | false | Enable debug logging |
| SPECTER_LOG_LEVEL | info | Log level (error/warn/info/debug) |
| SPECTER_TIMEOUT | 60000 | Default timeout (ms) |
| ANDROID_SDK_ROOT | auto | Android SDK path |
| SPECTER_ANDROID_DEVICE | - | Default Android device |
| SPECTER_IOS_DEVICE | booted | Default iOS simulator |

Troubleshooting

$3

`bash
export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools"
`

$3

`bash


Android: Start emulator

emulator -avd Pixel_6_API_34

iOS: Boot simulator

xcrun simctl boot "iPhone 15 Pro"
`

$3

`bash
xcode-select --install
`

$3

`json
{
"env": {
"SPECTER_DEBUG": "true",
"SPECTER_LOG_LEVEL": "debug"
}
}
`

Project Structure

`
src/
├── index.ts # MCP server entry
├── config.ts # Configuration
├── platforms/ # Android/iOS utilities
│ ├── android/ # ADB, Gradle, logcat
│ └── ios/ # simctl, xcodebuild, crash parsing
├── tools/ # MCP tool implementations
│ ├── build/ # build_app, install_app, launch_app
│ ├── ui/ # get_ui_context, interact_with_ui
│ ├── testing/ # run_unit_tests, run_maestro_flow, run_linter
│ ├── environment/ # list_devices, manage_env, clean_project
│ ├── crash/ # analyze_crash
│ ├── navigation/ # deep_link_navigate
│ └── observability/ # inspect_logs, inspect_app_state
└── utils/ # Shell, image processing, XML parsing
`

Development

`bash
npm install # Install dependencies
npm run build # Build TypeScript
npm test # Run tests (695 tests)
npm run test:coverage # Coverage report
npm run lint # ESLint
npm run typecheck # Type check
``

Documentation

- API Reference — All 15 tools with parameters
- Configuration Guide — Environment variables & setup
- Getting Started — First steps

License

MIT © Specter MCP Contributors