Content
# MoMoFish
*[阅读中文版](README.zh-CN.md)*
MoMoFish is an Android app that turns a spare phone into a local MCP perception server for Claude Code. It exposes camera, microphone, status, and watchdog tools over Streamable HTTP, runs Qwen3-VL with Alibaba MNN on-device when weights are installed, and keeps raw audio/video on the phone.
**Keywords:** Android MCP server, Claude Code phone camera, on-device AI monitor, Qwen3-VL MNN Android, Streamable HTTP MCP, local vision-language inference, developer watchdog.
## What is MoMoFish?
MoMoFish, also known as 摸摸鱼, lets Claude Code ask an Android device what it sees or hears without sending raw camera and microphone streams to a cloud service. The app hosts an MCP endpoint at `http://PHONE_IP:8765/mcp`, protects it with a bearer token, and returns structured perception results for tools such as `phone_look`, `phone_listen`, `phone_perceive`, `phone_status`, and `phone_watch_start`.
## Why use it?
| Need | MoMoFish provides |
| --- | --- |
| Give Claude Code physical-world context | Android camera and microphone exposed as MCP tools |
| Keep raw media local | On-device capture, local heuristic fallback, optional on-device Qwen3-VL/MNN inference |
| Monitor a desk, printer, board, or room | Watchdog tasks with periodic checks and SSE alerts |
| Run without model weights first | Heuristic degraded mode for setup, pairing, and connection tests |
| Add full vision-language inference later | Converted Qwen3-VL-2B MNN weights loaded from app-private storage |
## Quick Start
1. Open [`android-app/`](android-app/) in Android Studio.
2. Run the app on a physical Android device.
3. Grant camera, microphone, and notification permissions.
4. Tap **Start MCP Service** and copy the Claude command from the app.
5. On your computer, same Wi-Fi network:
```bash
claude mcp add --transport http --scope project momofish \
http://PHONE_IP:8765/mcp \
--header "Authorization: Bearer TOKEN"
```
Then ask Claude Code:
```text
Use phone_look to describe what the phone camera sees.
```
See [Claude Code setup](docs/claude-code-setup.md) for pairing, tokens, and SSE behavior.
## Model Files Are Not Included
This repository intentionally does **not** include model weights. Qwen3-VL/MNN model files are large and must be installed separately on the Android device.
Expected device path:
```text
/data/data/com.momofish.monitor/files/mnn_models/qwen3-vl-2b/
```
See [Model setup](docs/model-setup.md) for adb transfer steps and [MNN native build](docs/mnn-build.md) for `libMNN.so` notes.
## MCP Tools
| Tool | Purpose |
| --- | --- |
| `phone_look` | Ask a vision question about the current camera frame |
| `phone_listen` | Ask about recent microphone/audio context |
| `phone_perceive` | Combine visual and audio perception |
| `phone_status` | Read service, model, and pending alert status |
| `phone_watch_start` | Start periodic monitoring with alert rules |
| `phone_watch_stop` | Stop a watchdog task |
| `phone_watch_list` | List active watchdog tasks |
| `phone_look_raw` | Return a base64 JPEG fallback frame |
Schemas live in [`mcp-schemas/`](mcp-schemas/).
## Architecture
```text
Claude Code -- MCP Streamable HTTP/SSE --> Android Ktor server (:8765/mcp)
|
+-- CameraX frame capture
+-- AudioRecord ring buffer
+-- Qwen3-VL via MNN when installed
+-- Heuristic fallback when weights are absent
+-- Watchdog alerts and pending alert store
```
Read the full [architecture guide](docs/architecture.md).
## SEO and GEO Notes
This README uses plain answer blocks, question-based headings, tables, and explicit entity names so search engines and AI answer engines can cite the project accurately. The repository also includes [`llms.txt`](llms.txt) with concise guidance for AI crawlers and coding assistants.
Suggested GitHub topics: `android`, `kotlin`, `mcp`, `claude-code`, `qwen3-vl`, `mnn`, `on-device-ai`, `computer-vision`, `jetpack-compose`.
## Repository Layout
```text
android-app/ Kotlin Android app, MCP server, capture, inference, UI
mcp-schemas/ JSON schemas for MCP tools
prompts/ Vision-language, safety, and watchdog prompts
docs/ Architecture, setup, troubleshooting, tutorials
DOCUMENTS/ Tutorial images and walkthrough assets
skills/eyes-on-phone/ Codex/agent skill for using the phone tools
demo-scripts/ Demo helper notes
```
## Documentation
- [Tutorial](./DOCUMENTS/tutorial.md)
- [Architecture](docs/architecture.md) / [架构](docs/architecture.zh-CN.md)
- [Claude Code setup](docs/claude-code-setup.md) / [Claude Code 配置](docs/claude-code-setup.zh-CN.md)
- [Model setup](docs/model-setup.md) / [模型配置](docs/model-setup.zh-CN.md)
- [Pairing](docs/pairing.md) / [配对与认证](docs/pairing.zh-CN.md)
- [Advanced tunnel](docs/advanced-tunnel.md) / [远程访问](docs/advanced-tunnel.zh-CN.md)
- [Troubleshooting](docs/troubleshooting.md) / [故障排查](docs/troubleshooting.zh-CN.md)
- Tutorials: [dev board](docs/tutorials/dev-board.md), [3D print](docs/tutorials/3d-print.md), [smart home](docs/tutorials/smart-home.md)
## Privacy and Security
- Every MCP request requires a bearer token.
- The default cleartext HTTP endpoint is intended for trusted LAN use.
- Do not expose port `8765` to the public internet without a TLS tunnel and access control.
- Model weights, local captures, build outputs, and generated artifacts are excluded from the upload.
## License
MIT
