phonepi

PhonePi MCP turns your phone into a capable toolbox for AI assistants by exposing a range of phone-control features through the Model Context Protocol (MCP). This server lets compatible MCP clients—such as Cursor, Claude Desktop, or other MCP-enabled assistants—interact with your phone to manage contacts, messages, notes, and settings, as well as perform actions like sending SMS, making calls, sharing content, monitoring battery status, and setting reminders. The companion app handles permissions and securely bridges your phone with your local MCP-enabled apps, enabling natural language commands to be translated into device actions without exposing your data to external servers.

To use it, connect the MCP-enabled AI app to your PhonePi MCP server on your local network. Once connected, you can issue natural language commands like “Message Mom I’ll be there soon,” “Show me my recent battery status,” or “Remind me to call John at 3 PM.” The server processes requests, accesses the appropriate on-device capabilities through the companion app, and returns results or confirms actions. This setup emphasizes local-first operation with no third-party servers handling your data, provided you keep the server and app on a secure LAN.

The MCP tools available cover essential phone management tasks: contact and message handling, snippets and notes, device settings and notifications, SMS/call capabilities, cross-app content sharing, battery monitoring, timers and reminders, and Find My Phone functionality with audio alerts. As you use MCP-enabled AI assistants, you can chain actions (for example, search contacts, fetch a message, then respond) to automate common workflows across your devices.

Prerequisites:

• Node.js and npm installed on your machine
• Access to the PhonePi MCP repository or clone of this project
• A compatible MCP client app (e.g., Cursor, Claude Desktop) on your AI device

Step 1: Prepare the environment

• Ensure your phone and the host running the MCP server are on the same local network.
• Install dependencies (from the repository root):

  npm install
  

Step 2: Configure the server

• Create or edit the configuration file as needed. The example below runs the server via Node.js using a local server.js entry point.
• If your project uses a different entry file or port, adjust the values accordingly.

Step 3: Run the server

• Start the MCP server:

  npm run start
  

  or, if you run directly from the entry point:

  node server.js
  

Step 4: Connect an MCP client

• In your MCP client app, add a new MCP server using the host and port you started on (default 3000). Ensure local network access is permitted by your firewall.
• Authorize permissions on the phone app for the features you plan to use (contacts, messages, notifications, etc.).

Step 5: Verify

• Use a simple test phrase like “What is my battery status?” or “Show my most recent messages” to verify that the server responds correctly through the MCP client.

Tips and considerations:

• Security: Keep the server on a private network. Consider using VPN/tailscale for a secure LAN connection between devices.
• Permissions: The PhonePi MCP server relies on the companion app for on-device actions. You’ll need to grant appropriate permissions on the phone for each feature you intend to use (contacts, messages, notifications, etc.).
• Local-first by default: No third-party servers in the linking flow. If you introduce external services, ensure they are trusted and properly secured.
• Ports and firewalls: If you’re deploying on a restricted network, ensure the port used by the MCP server (default 3000) is allowed through the firewall.
• Logging: Adjust LOG_LEVEL to debug if you’re troubleshooting. Check logs for failed permission requests or missing capabilities on the device.
• Updates: Keep both the server and the companion app updated to ensure feature parity with MCP clients.