Keitai MCP 📱

Keitai MCP is an open-source Model Context Protocol (MCP) server and developer toolset designed specifically for AI agents (such as Antigravity, Claude, Cursor, Windsurf) and developers to interact with, automate, and develop software for Japanese Android feature phones ("ガラケー" / Garakei / Keitai), with first-class support for the Fujitsu arrows ケータイ F-03L (NTT DOCOMO).

🌟 Why Keitai MCP?

Japanese Android flip phones like the Fujitsu F-03L are unique beasts:

• No standard touchscreen: Navigation is driven primarily by a 5-way physical D-Pad, numeric keypad (0–9, *, #), and dedicated softkeys (F1, F2, CLR, CALL, ENDCALL).

• Compact resolution: 480 × 854 FWVGA display at 240 dpi.

• Clamshell form factor: Physical lid open/close sensor (gpio_lid).

• Architecture: 32-bit ARM (armeabi-v7a) on Qualcomm Snapdragon 210 running Android 8.1 Oreo (API 27) with 1 GB RAM.

Most general-purpose Android automation tools assume high-resolution touchscreens and modern touch gestures. When AI agents attempt to operate a Keitai, they often fail because they don't know:

1. Which UI element currently has D-Pad focus.

2. How to map physical keys (UP, DOWN, CENTER, CLR, F1, FAV1).

3. That screenshots must be scaled and captured efficiently without crashing low-memory buffers.

4. How to detect clamshell open/close states.

Keitai MCP bridges this gap completely. It equips LLM agents with native Keitai awareness, real-time vision, focus tracking, and hardware key controls.

Related MCP server: MobileAgentMCP

✨ Features

• 🎮 Physical Keypad Control: Send individual key events, long-presses, and complex multi-key sequences (UP, DOWN, CENTER/OK, BACK/CLR, F1, F2, 0–9, STAR, POUND, FAV1–FAV3).

• 👁️ Live Screen Vision: Capture 480×854 screenshots returned directly as MCP ImageContent for multimodal vision models, with automatic metadata (current package/activity).

• 🔍 Token-Efficient UI Hierarchy: Automatically parses uiautomator dump XML into a clean, readable text tree, clearly marking [★FOCUSED] elements, [CLICKABLE] items, and exact bounding box coordinates.

• 📦 App Management: Install APKs (with automated armeabi-v7a compatibility checks and runtime permissions), launch activities, force-stop, and clear app data.

• 🩺 Hardware & Battery Diagnostics: Real-time status of battery percentage, temperature (°C), voltage, clamshell lid state (OPEN / CLOSED), RAM availability, and Wi-Fi IP address.

• 📜 Logcat & Crash Diagnostics: Query logcat filtered by package PID, inspect the Android crash ring buffer (logcat -b crash), and capture fatal exception stack traces.

• 📁 Device File Transfer: Seamless push, pull, and ls on internal storage and microSD card.

• 📚 Embedded MCP Resources & Prompts: Built-in F-03L hardware specification sheets, Android Keitai development guidelines, and step-by-step navigation prompts.

• 💻 Rich CLI: Includes the keitai-mcp CLI for quick terminal inspection, device discovery, screenshots, and key injection.

📋 Requirements

1. Host Machine: Linux, macOS, or Windows.

2. Python: Python 3.10 or newer.

3. Android Platform Tools: adb command installed and available on your system PATH.

4. Device: Fujitsu arrows ケータイ F-03L (or compatible Android Keitai) connected via USB with USB Debugging enabled.

🚀 Quick Start

1. Installation

Clone and install using pip or pipx:

git clone https://github.com/haphuthinh/keitai_mcp.git
cd keitai_mcp
pip install -e .

Verify your connected Keitai:

keitai-mcp devices

Output:

                   Connected Android Devices                   
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Serial   ┃ State  ┃ Model ┃ Product ┃ F-03L Detected?       ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━┩
│ 96344868 │ device │ F_03L │ F03L    │ ✔ YES (Fujitsu F-03L) │
└──────────┴────────┴───────┴─────────┴───────────────────────┘

Inspect live device status:

keitai-mcp info

⚙️ MCP Client Configuration

Claude Desktop

Add keitai to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "keitai": {
      "command": "keitai-mcp",
      "args": ["run"]
    }
  }
}

Or using direct virtualenv Python:

{
  "mcpServers": {
    "keitai": {
      "command": "/path/to/keitai_mcp/.venv/bin/python",
      "args": ["-m", "keitai_mcp", "run"]
    }
  }
}

Antigravity

In Antigravity, MCP servers are configured globally in ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "keitai": {
      "command": "/path/to/keitai_mcp/.venv/bin/python",
      "args": ["-m", "keitai_mcp", "run"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Cursor / Windsurf / Zed

Add to your workspace or user MCP settings (mcpServers object):

{
  "mcpServers": {
    "keitai": {
      "command": "keitai-mcp",
      "args": ["run"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

🛠️ Complete MCP Tool Reference

Keitai MCP exposes 28 purpose-built tools:

📖 MCP Resources & Prompts

Resources

• keitai://f03l/specs: Complete technical hardware and software specifications of Fujitsu arrows Keitai F-03L.

• keitai://dev/guidelines: Comprehensive guide on developing Android applications for Japanese flip phones.

• keitai://dev/keycodes: Complete keycode catalog and mapping reference table.

Prompts

• plan_keitai_navigation(target_action): Guides an agent through inspecting the screen and executing D-Pad steps to reach an element.

• diagnose_keitai_crash(package_name): Diagnoses application crashes on Android 8.1 / armeabi-v7a.

🎛️ CLI Reference

Keitai MCP also includes a command-line interface:

# View help
keitai-mcp --help

# Show device status panel
keitai-mcp info

# Capture a screenshot
keitai-mcp screenshot -o screen.png

# Send a key event
keitai-mcp key UP
keitai-mcp key CENTER
keitai-mcp key BACK --count 2

# Inspect current UI tree
keitai-mcp ui
keitai-mcp ui --clickable-only

# List installed 3rd party apps
keitai-mcp apps
keitai-mcp apps --all --query docomo

📱 Hardware Profile: Fujitsu F-03L

For in-depth developer instructions, see KEITAI_DEVELOPMENT_GUIDE.md.

🧪 Testing

Keitai MCP has full unit and integration test coverage:

# Run test suite
pytest -v

If your Fujitsu F-03L is plugged in, pytest automatically runs the live integration tests (tests/test_live_device.py). If no device is connected, live tests are cleanly skipped.

🤝 Contributing

Contributions, issues, and feature requests are welcome! See CONTRIBUTING.md for setup and guidelines.

📄 License

This project is licensed under the MIT License.

keitai-mcp