PocketMCP

PocketMCP turns an Android phone into an MCP (Model Context Protocol) server. Once installed and running on your device, the server exposes an HTTP API over the local network (default port 8080) that external agents can call to retrieve device data, control apps, read notifications, and perform automation tasks via the built-in tools. Use the MCP client configuration to point at the phone’s LAN IP and port, or use Tailscale for remote access. The server supports a rich set of tools (device_info, get_location, search_contacts, make_call, send_message, social_media, notifications, shell, read_file, and many more) that let AI agents or desktop scripts query live data and issue actions on the phone in a controlled, secure manner with optional API key authentication.

To connect from a client, obtain the phone’s endpoint (for example http://<phone-ip>:8080/mcp) and issue JSON-RPC style requests as shown in the Quick Start examples. If you’re using a config file, add a server entry that points to the phone’s endpoint and supply any required API key in the headers or config as appropriate. For testing, you can use the health endpoint to verify the server is reachable and the tools/list method to enumerate available capabilities.

Prerequisites

• An Android device with PocketMCP installed (via APK or from source build) and the app running.
• Optional: a computer on the same LAN or a configured Tailscale network for remote access.
• API key (optional but recommended for security) configured in the PocketMCP app.

Installation steps

1. Install the PocketMCP app on your Android device

• Option A (pre-release): Install the APK from the v1.0.0-beta.1 release page.
• Option B (build from source): Build the APK locally and install it via ADB.

2. Launch and configure the server on the device

• Open PocketMCP on the phone.
• Set the port (default 8080).
• Generate or paste your API key in the app settings.
• Start the server from the UI and note the endpoint, typically http://<phone-ip>:8080/mcp.

3. Verify the server from a client on the same network

• Health check: curl http://<phone-ip>:8080/health
• List available tools: curl -X POST http://<phone-ip>:8080/mcp
  -H "Content-Type: application/json"
  -H "X-API-Key: your-api-key"
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. Configure MCP client configuration

• Create or update your mcp-config.json to point at the phone’s endpoint, e.g.: { "mcpServers": { "phone": { "type": "streamableHttp", "url": "http://<phone-ip>:8080/mcp" } } }

Notes

• If you’re on a remote network, enable Tailscale on the Android device and connect to the phone via the Tailscale IP.
• Ensure the phone remains on the same network or reachable via VPN for reliable operation.

Tips and common issues:

• Ensure the phone’s firewall allows inbound connections on port 8080, or configure the app to use a custom port.
• If you see timeouts, verify network reachability (ping the phone, confirm LAN IP) and ensure the API key is correctly supplied when making requests.
• The Defensive Shell and restricted file reads help protect the device; if a tool fails due to permission, review the app permissions and required accessibility/notification access as described in the Quick Start.
• When using emulator or VPN-based access, prefer local LAN IPs or dedicated tunnels (Tailscale) to maintain low latency and reliability.
• The tools list can reveal capabilities available on the current device; some tools require specific permissions (e.g., reading notifications, accessibility features) to function.
• For automation workflows, combine tools like http_request, shell, and app_actions to orchestrate complex sequences across apps and system states.