Content
CP
[](developer.android.com/guide/topics/uses-sdk-element)
[](https://spec.modelcontextprotocol.io/)
---
<h1 align="center">English Documentation</h1>
**The lightweight MCP server. No cloud VM needed — just an Android phone, and AI can call real-world capabilities.**
AndroidMCP runs a lightweight MCP protocol server directly on your Android device as a foreground service. AI clients — Claude Desktop, custom agents, anything supporting MCP — can discover and call tools on your phone over the standard MCP protocol.
> Plug it in, start the service, and the world is your terminal.
## Features
- **Android-native MCP server** — not a proxy, not a bridge, a real Ktor HTTP server running on your device speaking standard MCP Streamable HTTP
- **Device Tools** — read battery, storage, network info; send notifications; set alarms
- **Memory System** — persistent SQLite store with tag-based search and importance scoring. Give your AI agent long-term context across sessions
- **AI Diary** — the AI can write, read, search, and update diary entries. Read them from the app's home screen like peeking at someone's secret journal
- **Chinese OEM Support** — step-by-step guides for Xiaomi, Huawei, OPPO, vivo, and OnePlus background management settings (standard Android battery optimizations don't work on Chinese ROMs)
- **Privacy-first** — no telemetry, no analytics, no external servers. Everything runs locally on your device
## Tool List
### System Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `get_device_info` | Device information (battery, storage, network) | `info_type`: battery / storage / network / all |
| `send_notification` | Push a notification to the phone | `title`, `body`, `priority`(high/default/low) |
| `set_alarm` | Set an alarm via AlarmManager (works on emulators) | `hour`, `minute`, `label`(opt), `repeating`(opt) |
| `set_clock_alarm` | Set an alarm via the system clock app (supports weekdays) | `hour`, `minute`, `label`(opt), `days`(opt), `skip_ui`(opt) |
| `schedule_notification` | Schedule one or more notifications (supports batch and daily repeat) | `trigger_at`, `title`, `content`, `interval_days`(opt), `schedules`(opt batch array) |
### AI Memory
| Tool | Description | Parameters |
|------|-------------|------------|
| `save_memory` | Save a long-term memory | `content`, `tags`(opt array), `importance`(opt 1-10) |
| `search_memories` | Search memories (weighted scoring) | `query`(opt), `tags`(opt), `min_importance`(opt), `limit`(opt), `offset`(opt) |
| `update_memory` | Update an existing memory | `id`, `content`(opt), `tags`(opt), `importance`(opt) |
| `delete_memory` | Delete a memory | `id` |
### AI Diary
| Tool | Description | Parameters |
|------|-------------|------------|
| `write_diary` | Write a diary entry | `content`, `title`(opt), `mood`(opt) |
| `read_diary` | Read recent diary entries | `limit`(opt, default 10), `offset`(opt) |
| `search_diary` | Search diary entries by keyword | `query`, `limit`(opt, default 10), `offset`(opt) |
| `update_diary` | Update a specific diary entry | `id`, `title`(opt), `content`(opt), `mood`(opt) |
## Getting Started
### Requirements
- Android 8.0+ (API 26) — recommend a physical device for full functionality
- JDK 17+ and Android SDK installed on your build machine
### Build
```bash
# Option 1: One-click script (auto-detects JDK/SDK paths)
./scripts/build-apk.sh
# Option 2: Manual
./gradlew assembleDebug
```
APK path: `app/build/outputs/apk/debug/app-debug.apk`
### Install
```bash
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
### Run
1. Open the **AndroidMCP** app
2. Grant permissions on the "Permission Management" page (notifications, precise alarms)
3. Click **Start Service**
4. Status changes to "● Service Running", displaying `http://127.0.0.1:8765/mcp`
### Configure Desktop AI Client
In MCP client config (e.g., Claude Desktop's `claude_desktop_config.json`):
```json
{
"mcpServers": {
"android": {
"transport": "streamable-http",
"url": "http://<phone IP address>:8765/mcp"
}
}
}
```
> **Networking Note:** Phone and computer must be on the same LAN. If using USB or an emulator, run `adb forward tcp:8765 tcp:8765`, and use `http://127.0.0.1:8765/mcp`.
### Test with curl
```bash
# List tools
curl -s -X POST http://127.0.0.1:8765/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Get battery info
curl -s -X127.0.1:876cp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"","params":{"name":"get_device_info","arguments":{"info_type":"battery"}}}'
```
## Chinese Phone Background Survival
On international Android, `ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` prompts suffice foreground services alive. However, Chinese OEMs add an extra layer of "Startup Management / Auto-Start Management" on top of standard battery optimizations.
AndroidMCP auto-detects the device brand and displays OEM-specific steps on the **Permission Management** page:
| Brand | Steps |
|------|----------|
| Xiaomi / Redmi / POCO | Settings → App settings → App management → AndroidMCP → Disable smart restrictions in power saving, enable auto-start |
| Huawei / Honor | Settings → Battery → Find AndroidMCP → Disable automatic management, manually enable auto-start / associated start / background activity |
| OPPO / Realme | Settings → Battery → App power management → AndroidMCP → Disable automatic management, enable full background behavior |
| vivo / iQOO | Settings → Battery → Background power management → AndroidMCP → Choose allow high power consumption |
| OnePlus | Settings → Battery → Power optimization → AndroidMCP → Choose don't optimize |
Follow the instructions, then click **I have completed the settings** to confirm. Settings persist across reboots.
> **Note:** These provide visual guidance only. Chinese system settings activities require system-level signature permissions, which third-party apps cannot obtain, so direct launching from within the app is not possible.
## AI Diary
Before enabling the diary feature, call the `write_diary` tool in the MCP client to let AI write the first entry.
On the home screen, you'll see the "Her Diary" section — title, mood tags, time, and content summary. Click a card to expand the full text. Each time you switch back from another page, the diary list auto-refreshes.
Diary data is stored independently in `diaries.db`, separate from the memory system.
## Project Structure
```
android-mcp-server/
├── app/src/main/
│ ├── java/com/androidmcp/
│ │ ├── AndroidMCPApp.kt # Application entry point
│ │ ├── MainActivity.kt # Compose UI main interface + navigation
│ │ ├── permissions/
│ │ │ ├── PermissionManager.kt # Runtime permission management
│ │ │ └── OemAutostartManager.kt# OEM-specific autostart management
│ │ ├── server/
│ │ │ ├── MCPServer.kt # Ktor HTTP server
│ │ │ ├── MCPProtocolHandler.kt # JSON-RPC 2.0 protocol dispatch
│ │ │ └── ToolRegistry.kt # Tool registry
│ │ ├── service/
│ │ │ ├── MCPService.kt # Foreground service + tool registry
│ │ │ ├── AlarmReceiver.kt # Alarm broadcast receiver
│ │ │ └── ScheduledNotifReceiver.kt # Scheduled notification broadcast receiver
│ │ ├── tools/
│ │ │ ├── MCPTool.kt # Tool interface definition
│ │ │ ├── MemoryStore.kt # Memory SQLite storage
│ │ │ ├── DiaryStore.kt # Diary SQLite storage
│ │ │ ├── DeviceInfoTool.kt
│ │ │ ├── NotificationTool.kt
│ │ │ ├── AlarmTool.kt
│ │ │ ├── ClockAlarmTool.kt
│ │ │ ├── ScheduleNotificationTool.kt
│ │ │ ├── SaveMemoryTool.kt
│ │ │ ├── SearchMemoriesTool.kt
│ │ │ ├── UpdateMemoryTool.kt
│ │ │ ├── DeleteMemoryTool.kt
│ │ │ ├── WriteDiaryTool.kt
│ │ │ ├── ReadDiaryTool.kt
│ │ │ ├── SearchDiaryTool.kt
│ │ │ └── UpdateDiaryTool.kt
│ │ └── ui/
│ │ ├── components/
│ │ │ └── AppChrome.kt # Top bar + bottom navigation
│ │ ├── DiaryScreen.kt # Diary reading page
│ │ ├── MainScreen.kt # Main interface
│ │ ├── PermissionsScreen.kt # Permission management page
│ │ ├── SettingsScreen.kt # Port configuration
│ │ ├── theme/
│ │ │ ├── Color.kt # Theme colors
│ │ │ ├── Shape.kt # Shape definitions
│ │ │ ├── Theme.kt # Material 3 theme
│ │ │ └── Type.kt # Typography
│ │ └── ToolsScreen.kt # Tool browser
│ ├── AndroidManifest.xml
│ └── res/values/
│ ├── strings.xml
│ └── themes.xml
├── scripts/
│ └── build-apk.sh
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
└── gradlew
```
## Privacy Statement
- **No data leaves the device.** No telemetry, no analytics reporting, no external server connections. The MCP protocol only listens on `127.0.0.1` (you can also configure a LAN client).
- **No background data collection.** The app does not collect, store, or transmit any personal information.
- **Fully open-source.** Every line of code is reviewable, with no binary blobs or obfuscation.
## Tech Stack
| Layer | Selection |
|------|-----------|
| Language | Kotlin |
| UI | Jetpack Compose + Material 3 |
| HTTP Server | Ktor CIO |
| Serialization | kotlinx-serialization |
| Storage | SQLite (native, no ORM) |
| Protocol | MCP Streamable HTTP (2025-03-26) |
| Background Survival | Android Foreground Service (START_STICKY) |
| Build | Gradle 8.5 + AGP 8.2.0 |
| Min / Target SDK | 26 (Android 8.0) / 35 (Android 15) |
## License
MIT — see [LICENSE](LICENSE).
### AI Memory
| Tool | Description | Parameters |
|------|-------------|------------|
| `save_memory` | Save a long-term memory with tags and importance | `content`, `tags`(opt array), `importance`(opt 1-10) |
| `search_memories` | Search memories with weighted scoring | `query`(opt), `tags`(opt), `min_importance`(opt), `limit`(opt), `offset`(opt) |
| `update_memory` | Update an existing memory by ID | `id`, `content`(opt), `tags`(opt), `importance`(opt) |
| `delete_memory` | Delete a memory by ID | `id` |
### AI Diary
| Tool | Description | Parameters |
|------|-------------|------------|
| `write_diary` | Write a personal diary entry | `content`, `title`(opt), `mood`(opt) |
| `read_diary` | Read recent diary entries | `limit`(opt, default 10), `offset`(opt) |
| `search_diary` | Search diary entries by keyword | `query`, `limit`(opt, default 10), `offset`(opt) |
| `update_diary` | Modify an existing diary entry by ID | `id`, `title`(opt), `content`(opt), `mood`(opt) |
## Quick Start
### Prerequisites
- Android 8.0+ device (API 26) — physical device recommended for full functionality
- JDK 17+ and Android SDK installed on your build machine
### Build
```bash
# Option 1: use the helper script (auto-detects JDK/SDK paths)
./scripts/build-apk.sh
# Option 2: manual
./gradlew assembleDebug
```
APK output: `app/build/outputs/apk/debug/app-debug.apk`
### Install
```bash
adb install -r app/build/outputs/apk/debug/app-debug.apk
```
### Use
1. Open the **AndroidMCP** app on your phone
2. Grant the requested permissions (notifications, exact alarm when needed)
3. Tap **Start Server**
4. The status changes to "● Service Running" with the URL `http://127.0.0.1:8765/mcp`
### Connect from a Desktop AI Client
Add to your MCP client configuration (e.g. Claude Desktop `claude_desktop_config.json`):
```json
{
"mcpServers": {
"android": {
"transport": "streamable-http",
"url": "http://<phone-ip>:8765/mcp"
}
}
}
```
> **Network note:** Phone and computer must be on the same network. For USB-tethered setups or emulators, use `adb forward tcp:8765 tcp:8765` and connect to `http://127.0.0.1:8765/mcp`.
### Test with curl
```bash
# List available tools
curl -s -X POST http://127.0.0.1:8765/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# Get device battery info
curl -s -X POST http://127.0.0.1:8765/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_device_info","arguments":{"info_type":"battery"}}}'
```
## OEM Background Management
On most international Android devices, `ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` is sufficient to keep a foreground service alive. However, Chinese ROMs (Huawei, Xiaomi, OPPO, vivo, OnePlus) add proprietary startup and background management layers that kill processes regardless of the standard battery optimization setting.
The app detects the device manufacturer and shows brand-specific setup instructions in the **Permissions** screen:
| Brand | Required Steps |
|-------|----------------|
| Xiaomi / Redmi / POCO | Settings → Apps → disable power saver restrictions, enable autostart |
| Huawei / Honor | Settings → Battery → find the app → disable auto management, enable all three toggles |
| OPPO / Realme | Settings → Battery → App Power Consumption → disable auto management, allow full background |
| vivo / iQOO | Settings → Battery → Background Power Consumption → select "Allow high power consumption" |
| OnePlus | Settings → Battery → Battery Optimization → select "Don't optimize" |
After following the steps, tap **I've completed the setup** to acknowledge. The setting persists across app restarts.
> **Note:** These are manual instructions only. OEM settings activities require system-level signature permissions that third-party apps cannot obtain, so programmatic navigation from within the app is not possible.
## AI Diary
After setting up, ask your AI to call `write_diary` to write the first entry. Then open the app's home screen — you'll see the **Her Diary** section showing titles, mood labels, timestamps, and content previews. Tap a card to expand the full entry. The list auto-refreshes when you return to the app.
Diary data is stored separately in `diaries.db`, independent from the memory system.
## Architecture
```
┌────────────────────────────────────────────┐
│ AndroidMCP App │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ MainActivity │ │
│ │ ├── MainScreen (server control, │ │
│ │ │ diary reader, navigation) │ │
│ │ ├── PermissionsScreen (runtime + │ │
│ │ │ OEM setup guides) │ │
│ │ ├── SettingsScreen (port config) │ │
│ │ └── ToolsScreen (tool browser) │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ MCPService (Foreground Service) │ │
│ │ ├── MCPServer (Ktor CIO, port 8765) │ │
│ │ ├── MCPProtocolHandler │ │
│ │ └── ToolRegistry │ │
│ │ ├── system/ (alarm, device, │ │
│ │ │ notification) │ │
│ │ ├── memory/ (save, search, │ │
│ │ │ update, delete) │ │
│ │ └── diary/ (write, read, │ │
│ │ search, update) │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ memories.db │ │ diaries.db │ │
│ │ (SQLite) │ │ (SQLite) │ │
│ └──────────────┘ └──────────────┘ │
└────────────────────────────────────────────┘
```
## Project Structure
```
android-mcp-server/
├── app/src/main/
│ ├── java/com/androidmcp/
│ │ ├── AndroidMCPApp.kt # Application entry
│ │ ├── MainActivity.kt # Compose UI root + navigation
│ │ ├── permissions/
│ │ │ ├── PermissionManager.kt # Runtime permission state
│ │ │ └── OemAutostartManager.kt# OEM detection + guides
│ │ ├── server/
│ │ │ ├── MCPServer.kt # Ktor HTTP server
│ │ │ ├── MCPProtocolHandler.kt # JSON-RPC 2.0 dispatcher
│ │ │ └── ToolRegistry.kt # Tool registration map
│ │ ├── service/
│ │ │ ├── MCPService.kt # Foreground service + tool wiring
│ │ │ ├── AlarmReceiver.kt # Alarm broadcast receiver
│ │ │ └── ScheduledNotifReceiver.kt # Scheduled notification receiver
│ │ ├── tools/
│ │ │ ├── MCPTool.kt # Tool interface
│ │ │ ├── MemoryStore.kt # SQLite memory storage
│ │ │ ├── DiaryStore.kt # SQLite diary storage
│ │ │ ├── DeviceInfoTool.kt
│ │ │ ├── NotificationTool.kt
│ │ │ ├── AlarmTool.kt
│ │ │ ├── ClockAlarmTool.kt
│ │ │ ├── ScheduleNotificationTool.kt
│ │ │ ├── SaveMemoryTool.kt
│ │ │ ├── SearchMemoriesTool.kt
│ │ │ ├── UpdateMemoryTool.kt
│ │ │ ├── DeleteMemoryTool.kt
│ │ │ ├── WriteDiaryTool.kt
│ │ │ ├── ReadDiaryTool.kt
│ │ │ ├── SearchDiaryTool.kt
│ │ │ └── UpdateDiaryTool.kt
│ │ └── ui/
│ │ ├── components/
│ │ │ └── AppChrome.kt # Top bar + bottom nav
│ │ ├── DiaryScreen.kt # Diary reader page
│ │ ├── MainScreen.kt # Home screen
│ │ ├── PermissionsScreen.kt # Permission management
│ │ ├── SettingsScreen.kt # Port configuration
│ │ ├── theme/
│ │ │ ├── Color.kt # Theme colors
│ │ │ ├── Shape.kt # Shape definitions
│ │ │ ├── Theme.kt # Material 3 theme
│ │ │ └── Type.kt # Typography
│ │ └── ToolsScreen.kt # Tool browser
│ ├── AndroidManifest.xml
│ └── res/values/
│ ├── strings.xml
│ └── themes.xml
├── scripts/
│ └── build-apk.sh # Build helper
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
└── gradlew
```
## Tech Stack
| Layer | Choice |
|-------|--------|
| Language | Kotlin |
| UI | Jetpack Compose + Material 3 |
| HTTP Server | Ktor CIO |
| Serialization | kotlinx-serialization |
| Storage | SQLite (raw, no ORM) |
| Protocol | MCP Streamable HTTP (2025-03-26) |
| Background | Android Foreground Service (START_STICKY) |
| Build | Gradle 8.5 + AGP 8.2.0 |
| Min / Target SDK | 26 (Android 8.0) / 35 (Android 15) |
## Privacy
- **No data leaves your device.** All processing is local; there are no telemetry, analytics, or network calls to external servers, other than the MCP protocol itself which runs on `127.0.0.1` (or your LAN if you configure a remote client).
- **No background data collection.** The app does not collect, store, or transmit any personal information.
- **Fully open source.** Every line of code can be inspected. No binary blobs, no obfuscation.
## License
MIT — see [LICENSE](LICENSE).
---
Built with ❤️ for AI companions and the people who love them.
