Skip to content
/ PocketMCP Public

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.

License

MIT license
2 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

axonixtools/PocketMCP

BranchesTags

Repository files navigation

PocketMCP

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.

Download (Testing Pre-release)

  • Latest testing release: v1.0.0-beta.1
  • This build is marked as pre-release and may contain bugs while active development continues.

Open-Source Commitment

PocketMCP is fully open-source and core functionality is free. The project is MIT-licensed and community contributions are welcome.

Why this is useful

High-value use cases for all users:

  1. Communication Hub: Send WhatsApp, Instagram, Messenger messages and make calls from desktop
  2. Social Media Automation: Interact with Instagram, YouTube, X/Twitter automatically
  3. Notification Management: Monitor and respond to all phone notifications in real-time
  4. Daily readiness check: "What is my battery and where is my phone right now?"
  5. Contact lookup: "Find Alice's number from my phone contacts."
  6. App ecosystem control: Launch and manage 309+ installed applications
  7. Phone diagnostics: Run safe shell checks without unlocking the phone.

Built-in tools

Tool Description
device_info Battery, model, OS, network, memory
get_location Best recent location from device providers
search_contacts Search contacts by name
make_call Make phone calls to any number
send_message Send messages via WhatsApp, Instagram, Messenger, Google Messages
send_whatsapp_business_message Dedicated WhatsApp Business contact-safe sender
whatsapp_automation Advanced WhatsApp automation with accessibility control
social_media Instagram, YouTube, X/Twitter interactions
app_actions JSON-preset actions for simpler app automation calls
notifications Real-time notification monitoring and management
shell Run shell commands with safety filters and timeout
flashlight Turn flashlight on/off/toggle and read state
launch_app Open an installed app by package or app name
list_apps List launchable installed apps (309+ apps detected)
global_action Home/back/recents/notifications/quick settings/lock screen
scroll_screen Scroll current app via accessibility gesture
search_screen Find search input on current screen and type query safely
tap Tap by visible text/content description or screen coordinates
volume_control Read and change stream volume levels
phone_alert Ring and/or vibrate phone to help locate it quickly
voice_record Record voice notes from microphone
transcribe_audio Speech-to-text from microphone or local audio file path
transcribe_file Direct audio-file transcription by path
transcribe_whatsapp_audio Transcribe latest WhatsApp/WhatsApp Business voice note
human_command Natural-language command router across major tools
http_request Make outbound HTTP requests from phone
read_file Read files from allowed storage paths

🆕 New Features (v.0+)

📞 Phone Calling & Messaging

  • Direct Calls: Make phone calls to any number with contact name support
  • Multi-Platform Messaging: WhatsApp, Instagram, Messenger, Google Messages
  • WhatsApp Business Support: Prioritizes WhatsApp Business when installed
  • Deep Link Integration: Opens apps with pre-filled content

🤖 Advanced WhatsApp Automation

  • Complete Automation: Send messages with contact selection and typing
  • Step-by-Step Control: Select contacts, type messages, press send/cancel
  • Accessibility Integration: Full UI automation via accessibility service
  • Business & Personal: Supports both WhatsApp variants

🌐 Social Media Interactions

  • Instagram: Profile search, post interactions (like, comment, share)
  • YouTube: Video search, like/dislike/comment on videos
  • X/Twitter: Profile search, post interactions
  • Deep Links: Direct navigation to specific content

🔔 Real-Time Notifications

  • Live Monitoring: Capture all device notifications in real-time
  • Full Data: Title, text, app, time, priority, visibility
  • Historical Access: Recent notifications with search and filtering
  • Management: Clear history, check status, get counts

Security model

  • API key authentication supported via X-API-Key (recommended).
  • Local network usage by default; use Tailscale for remote access.
  • Shell tool blocks high-risk commands and enforces timeout/output limits.
  • File reads are restricted to app storage and external storage roots.
  • Loopback URLs are blocked in http_request.
  • Accessibility Service: Required for advanced automation features.
  • Notification Access: Required for real-time notification monitoring.

Reliability model

  • Android foreground service keeps MCP server alive.
  • Start/stop/status lifecycle is explicit (START, STOP, QUERY_STATUS).
  • UI reflects actual service state using status broadcasts.
  • Enhanced App Discovery: Detects 309+ launchable apps (up from 25).
  • Graceful Fallbacks: Manual interaction instructions when automation not possible.

Quick start

1) Install app

Option A: install from pre-release APK

  • Download PocketMCP-debug.apk from v1.0.0-beta.1
  • Install with ADB:
adb install -r PocketMCP-debug.apk

Option B: build from source and install

./gradlew assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk

2) Start server in app

  1. Open PocketMCP.
  2. Set port (default 8080).
  3. Generate or paste API key.
  4. Start server from switch or button.
  5. Copy endpoint/config from the Quick Connect section.

3) Enable Permissions

Required for full functionality:

  • Phone: CALL_PHONE permission in app settings
  • Microphone: RECORD_AUDIO permission in app settings
  • SMS: SEND_SMS, READ_SMS permissions
  • Notifications: Settings > Apps > Special Access > Notification Access
  • Accessibility: Settings > Apps > Special Access > Accessibility Services

4) Verify server

# health
curl http://192.168.1.100:8080/health

# list tools
curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Emulator connection (Android Studio AVD)

If PocketMCP runs inside an Android emulator, do not use 10.0.2.15 from your host MCP client config.

Use ADB port forwarding and localhost:

powershell -ExecutionPolicy Bypass -File .\scripts\setup-emulator-mcp.ps1

Then set MCP URL to:

http://127.0.0.1:8080/mcp

Notes:

  • 10.0.2.15 is emulator-internal (not host-reachable).
  • 10.0.2.2 is for emulator -> host, not host -> emulator.

MCP Client Config Example

Use mcp-config.example.json as a template.

{
  "mcpServers": {
    "phone": {
      "type": "streamableHttp",
      "url": "http://192.168.1.100:8080/mcp",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Stdio Bridge (for stdio-only MCP clients)

PocketMCP includes a hardened stdio bridge in mcp-bridge/bridge.mjs that proxies stdio MCP calls to your phone's HTTP MCP endpoint.

cd mcp-bridge
npm install
node bridge.mjs --url http://192.168.1.100:8080/mcp --api-key your-api-key --verbose

Bridge configuration options:

  • --url: target phone MCP URL (auto-adds http:// if missing)
  • --api-key: API key sent as X-API-Key
  • --timeout-ms: per-request timeout (default 20000)
  • --tools-ttl-ms: tool cache TTL (default 30000)
  • --no-tool-cache: disable tool caching
  • --verbose: emit detailed bridge logs to stderr

Equivalent environment variables:

  • POCKET_MCP_URL
  • POCKET_MCP_API_KEY
  • POCKET_MCP_TIMEOUT_MS
  • POCKET_MCP_TOOLS_TTL_MS
  • POCKET_MCP_DISABLE_TOOL_CACHE=1
  • POCKET_MCP_VERBOSE=1

Python Client Example

from pocket_mcp_client import PocketMCPClient

phone = PocketMCPClient("http://192.168.1.100:8080", api_key="your-api-key")

print(phone.device_info())
print(phone.list_apps(limit=25))
print(phone.notifications("list", 10))
print(phone.human_command("vibrate my phone for 5 seconds"))

Python client now includes retries, typed exceptions, stricter argument validation, and a CLI:

# health check (default action)
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key

# list tools
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key --list-tools

# call one tool with JSON args
python3 pocket_mcp_client.py 192.168.1.100:8080 your-api-key \
  --call send_message \
  --args '{"app":"whatsapp","phone_number":"+15551234567","message":"hello from desktop"}'

Permissions

Some tools require Android special permissions or services:

  • Phone (CALL_PHONE)
  • Microphone (RECORD_AUDIO)
  • SMS (SEND_SMS, READ_SMS, RECEIVE_SMS)
  • Notifications access (Notification Listener)
  • Accessibility service (for UI automation)

Security Model

  • API key authentication through X-API-Key (recommended)
  • Local network first; remote access via private networks like Tailscale
  • Shell command restrictions with timeout/output limits
  • File-read path restrictions
  • Loopback URL blocking for http_request

Reliability Notes

  • Runs as an Android foreground service
  • Explicit service lifecycle (START, STOP, QUERY_STATUS)
  • Status broadcast updates reflected in UI

Roadmap

  • Camera capture tools
  • More accessibility-driven automations
  • WebSocket support
  • One-tap pairing workflow
  • Voice-first command flows

License

MIT

About

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.

Topics

android open-source automation mcp json-rpc self-hosted python-client developer-tools mobile-automation android-automation ktor accessibility-service notification-listener ai-tools ai-agent voice-transcription agentic-ai model-context-protocol phone-automation pocketmcp

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Languages