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.

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:

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

Built-in tools

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

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

2) Start server in app

Open PocketMCP.
Set port (default 8080).
Generate or paste API key.
Start server from switch or button.
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

3) 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"}'

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"
      }
    }
  }
}

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"))

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

MCP Servers