{"id":49719335,"url":"https://github.com/axonixtools/PocketMCP","last_synced_at":"2026-05-25T12:01:01.837Z","repository":{"id":339366198,"uuid":"1161611978","full_name":"axonixtools/PocketMCP","owner":"axonixtools","description":"Turn your Android phone into an MCP (Model Context Protocol) server. AI agents and desktop scripts can call your phone for live data and actions over LAN or Tailscale.","archived":false,"fork":false,"pushed_at":"2026-02-19T10:49:07.000Z","size":163,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-19T15:12:22.423Z","etag":null,"topics":["accessibility-service","agentic-ai","ai-agent","ai-tools","android","android-automation","automation","developer-tools","json-rpc","ktor","mcp","mobile-automation","model-context-protocol","notification-listener","open-source","phone-automation","pocketmcp","python-client","self-hosted","voice-transcription"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axonixtools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T10:08:17.000Z","updated_at":"2026-02-19T10:49:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/axonixtools/PocketMCP","commit_stats":null,"previous_names":["axonixtools/pocketmcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/axonixtools/PocketMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonixtools%2FPocketMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonixtools%2FPocketMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonixtools%2FPocketMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonixtools%2FPocketMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axonixtools","download_url":"https://codeload.github.com/axonixtools/PocketMCP/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axonixtools%2FPocketMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33473706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility-service","agentic-ai","ai-agent","ai-tools","android","android-automation","automation","developer-tools","json-rpc","ktor","mcp","mobile-automation","model-context-protocol","notification-listener","open-source","phone-automation","pocketmcp","python-client","self-hosted","voice-transcription"],"created_at":"2026-05-08T23:00:41.358Z","updated_at":"2026-05-25T12:01:01.806Z","avatar_url":"https://github.com/axonixtools.png","language":"Kotlin","funding_links":[],"categories":["Servers"],"sub_categories":[],"readme":"# PocketMCP\n\nTurn your Android phone into an MCP (Model Context Protocol) server.\nAI agents and desktop scripts can call your phone for live data and actions over LAN or Tailscale.\n\n## Download (Testing Pre-release)\n\n- Latest testing release: [v1.0.0-beta.1](https://github.com/axonixtools/PocketMCP/releases/tag/v1.0.0-beta.1)\n- This build is marked as pre-release and may contain bugs while active development continues.\n\n## Open-Source Commitment\n\nPocketMCP is fully open-source and core functionality is free.\nThe project is MIT-licensed and community contributions are welcome.\n\n## Why this is useful\n\n**High-value use cases for all users:**\n\n1. **Communication Hub**: Send WhatsApp, Instagram, Messenger messages and make calls from desktop\n2. **Social Media Automation**: Interact with Instagram, YouTube, X/Twitter automatically\n3. **Notification Management**: Monitor and respond to all phone notifications in real-time\n4. **Daily readiness check**: \"What is my battery and where is my phone right now?\"\n5. **Contact lookup**: \"Find Alice's number from my phone contacts.\"\n6. **App ecosystem control**: Launch and manage 309+ installed applications\n7. **Phone diagnostics**: Run safe shell checks without unlocking the phone.\n\n## Built-in tools\n\n| Tool                  | Description                                                       |\n| --------------------- | ----------------------------------------------------------------- |\n| `device_info`         | Battery, model, OS, network, memory                               |\n| `get_location`        | Best recent location from device providers                        |\n| `search_contacts`     | Search contacts by name                                           |\n| `make_call`           | Make phone calls to any number                                    |\n| `send_message`        | Send messages via WhatsApp, Instagram, Messenger, Google Messages |\n| `send_whatsapp_business_message` | Dedicated WhatsApp Business contact-safe sender      |\n| `whatsapp_automation` | Advanced WhatsApp automation with accessibility control           |\n| `social_media`        | Instagram, YouTube, X/Twitter interactions                        |\n| `app_actions`         | JSON-preset actions for simpler app automation calls              |\n| `notifications`       | Real-time notification monitoring and management                  |\n| `shell`               | Run shell commands with safety filters and timeout                |\n| `flashlight`          | Turn flashlight on/off/toggle and read state                      |\n| `launch_app`          | Open an installed app by package or app name                      |\n| `list_apps`           | List launchable installed apps (309+ apps detected)               |\n| `global_action`       | Home/back/recents/notifications/quick settings/lock screen        |\n| `scroll_screen`       | Scroll current app via accessibility gesture                      |\n| `search_screen`       | Find search input on current screen and type query safely         |\n| `tap`                 | Tap by visible text/content description or screen coordinates     |\n| `volume_control`      | Read and change stream volume levels                              |\n| `phone_alert`         | Ring and/or vibrate phone to help locate it quickly               |\n| `voice_record`        | Record voice notes from microphone                                |\n| `transcribe_audio`    | Speech-to-text from microphone or local audio file path          |\n| `transcribe_file`     | Direct audio-file transcription by path                           |\n| `transcribe_whatsapp_audio` | Transcribe latest WhatsApp/WhatsApp Business voice note     |\n| `human_command`       | Natural-language command router across major tools                |\n| `http_request`        | Make outbound HTTP requests from phone                            |\n| `read_file`           | Read files from allowed storage paths                             |\n\n## 🆕 New Features (v.0+)\n\n### 📞 **Phone Calling \u0026 Messaging**\n\n- **Direct Calls**: Make phone calls to any number with contact name support\n- **Multi-Platform Messaging**: WhatsApp, Instagram, Messenger, Google Messages\n- **WhatsApp Business Support**: Prioritizes WhatsApp Business when installed\n- **Deep Link Integration**: Opens apps with pre-filled content\n\n### 🤖 **Advanced WhatsApp Automation**\n\n- **Complete Automation**: Send messages with contact selection and typing\n- **Step-by-Step Control**: Select contacts, type messages, press send/cancel\n- **Accessibility Integration**: Full UI automation via accessibility service\n- **Business \u0026 Personal**: Supports both WhatsApp variants\n\n### 🌐 **Social Media Interactions**\n\n- **Instagram**: Profile search, post interactions (like, comment, share)\n- **YouTube**: Video search, like/dislike/comment on videos\n- **X/Twitter**: Profile search, post interactions\n- **Deep Links**: Direct navigation to specific content\n\n### 🔔 **Real-Time Notifications**\n\n- **Live Monitoring**: Capture all device notifications in real-time\n- **Full Data**: Title, text, app, time, priority, visibility\n- **Historical Access**: Recent notifications with search and filtering\n- **Management**: Clear history, check status, get counts\n\n## Security model\n\n- API key authentication supported via `X-API-Key` (recommended).\n- Local network usage by default; use Tailscale for remote access.\n- Shell tool blocks high-risk commands and enforces timeout/output limits.\n- File reads are restricted to app storage and external storage roots.\n- Loopback URLs are blocked in `http_request`.\n- **Accessibility Service**: Required for advanced automation features.\n- **Notification Access**: Required for real-time notification monitoring.\n\n## Reliability model\n\n- Android foreground service keeps MCP server alive.\n- Start/stop/status lifecycle is explicit (`START`, `STOP`, `QUERY_STATUS`).\n- UI reflects actual service state using status broadcasts.\n- **Enhanced App Discovery**: Detects 309+ launchable apps (up from 25).\n- **Graceful Fallbacks**: Manual interaction instructions when automation not possible.\n\n## Quick start\n\n### 1) Install app\n\nOption A: install from pre-release APK\n\n- Download `PocketMCP-debug.apk` from [v1.0.0-beta.1](https://github.com/axonixtools/PocketMCP/releases/tag/v1.0.0-beta.1)\n- Install with ADB:\n\n```bash\nadb install -r PocketMCP-debug.apk\n```\n\nOption B: build from source and install\n\n```bash\n./gradlew assembleDebug\nadb install app/build/outputs/apk/debug/app-debug.apk\n```\n\n### 2) Start server in app\n\n1. Open PocketMCP.\n2. Set port (default `8080`).\n3. Generate or paste API key.\n4. Start server from switch or button.\n5. Copy endpoint/config from the Quick Connect section.\n\n### 3) Enable Permissions\n\n**Required for full functionality:**\n\n- **Phone**: CALL_PHONE permission in app settings\n- **Microphone**: RECORD_AUDIO permission in app settings\n- **SMS**: SEND_SMS, READ_SMS permissions\n- **Notifications**: Settings \u003e Apps \u003e Special Access \u003e Notification Access\n- **Accessibility**: Settings \u003e Apps \u003e Special Access \u003e Accessibility Services\n\n### 4) Verify server\n\n```bash\n# health\ncurl http://192.168.1.100:8080/health\n\n# list tools\ncurl -X POST http://192.168.1.100:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: your-api-key\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\n### Emulator connection (Android Studio AVD)\n\nIf PocketMCP runs inside an Android emulator, do **not** use `10.0.2.15` from your host MCP client config.\n\nUse ADB port forwarding and localhost:\n\n```powershell\npowershell -ExecutionPolicy Bypass -File .\\scripts\\setup-emulator-mcp.ps1\n```\n\nThen set MCP URL to:\n\n```text\nhttp://127.0.0.1:8080/mcp\n```\n\nNotes:\n- `10.0.2.15` is emulator-internal (not host-reachable).\n- `10.0.2.2` is for emulator -\u003e host, not host -\u003e emulator.\n\n## MCP Client Config Example\n\nUse `mcp-config.example.json` as a template.\n\n```json\n{\n  \"mcpServers\": {\n    \"phone\": {\n      \"type\": \"streamableHttp\",\n      \"url\": \"http://192.168.1.100:8080/mcp\",\n      \"headers\": {\n        \"X-API-Key\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n## Stdio Bridge (for stdio-only MCP clients)\n\nPocketMCP includes a hardened stdio bridge in `mcp-bridge/bridge.mjs` that proxies stdio MCP calls to your phone's HTTP MCP endpoint.\n\n```bash\ncd mcp-bridge\nnpm install\nnode bridge.mjs --url http://192.168.1.100:8080/mcp --api-key your-api-key --verbose\n```\n\nBridge configuration options:\n\n- `--url`: target phone MCP URL (auto-adds `http://` if missing)\n- `--api-key`: API key sent as `X-API-Key`\n- `--timeout-ms`: per-request timeout (default `20000`)\n- `--tools-ttl-ms`: tool cache TTL (default `30000`)\n- `--no-tool-cache`: disable tool caching\n- `--verbose`: emit detailed bridge logs to stderr\n\nEquivalent environment variables:\n\n- `POCKET_MCP_URL`\n- `POCKET_MCP_API_KEY`\n- `POCKET_MCP_TIMEOUT_MS`\n- `POCKET_MCP_TOOLS_TTL_MS`\n- `POCKET_MCP_DISABLE_TOOL_CACHE=1`\n- `POCKET_MCP_VERBOSE=1`\n\n## Python Client Example\n\n```python\nfrom pocket_mcp_client import PocketMCPClient\n\nphone = PocketMCPClient(\"http://192.168.1.100:8080\", api_key=\"your-api-key\")\n\nprint(phone.device_info())\nprint(phone.list_apps(limit=25))\nprint(phone.notifications(\"list\", 10))\nprint(phone.human_command(\"vibrate my phone for 5 seconds\"))\n```\n\nPython client now includes retries, typed exceptions, stricter argument validation, and a CLI:\n\n```bash\n# health check (default action)\npython3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key\n\n# list tools\npython3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key --list-tools\n\n# call one tool with JSON args\npython3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key \\\n  --call send_message \\\n  --args '{\"app\":\"whatsapp\",\"phone_number\":\"+15551234567\",\"message\":\"hello from desktop\"}'\n```\n\n## Permissions\n\nSome tools require Android special permissions or services:\n\n- Phone (`CALL_PHONE`)\n- Microphone (`RECORD_AUDIO`)\n- SMS (`SEND_SMS`, `READ_SMS`, `RECEIVE_SMS`)\n- Notifications access (Notification Listener)\n- Accessibility service (for UI automation)\n\n## Security Model\n\n- API key authentication through `X-API-Key` (recommended)\n- Local network first; remote access via private networks like Tailscale\n- Shell command restrictions with timeout/output limits\n- File-read path restrictions\n- Loopback URL blocking for `http_request`\n\n## Reliability Notes\n\n- Runs as an Android foreground service\n- Explicit service lifecycle (`START`, `STOP`, `QUERY_STATUS`)\n- Status broadcast updates reflected in UI\n\n## Roadmap\n\n- Camera capture tools\n- More accessibility-driven automations\n- WebSocket support\n- One-tap pairing workflow\n- Voice-first command flows\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonixtools%2FPocketMCP","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxonixtools%2FPocketMCP","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxonixtools%2FPocketMCP/lists"}