PhoneConnect

Experimental bridge: connect your Android phone to a Cursor Cloud Agent so the agent can use PocketMCP tools (tap, apps, screen state) over a Tailscale SOCKS5 link.

Status: experimental · Requires: Android + PocketMCP + Tailscale + Cursor Cloud Agent · MIT

Project age: first commit on 2026-07-15.

Quality: CI (ShellCheck, bridge smoke, npm audit) · CodeQL · Dependabot · Vercel ignoreCommand waits for CI + CodeQL if hosted on Vercel

Not a production product. API and scripts may change without notice.

---

Quick start

1. Phone

• Install Tailscale + PocketMCP on Android.
• Set a PocketMCP API key in the app.
• Note your phone's Tailscale IP (e.g. 100.x.y.z).

2. Tailscale key

Create an auth key at login.tailscale.com/admin/settings/keys.

3. Cursor secrets

In Cursor Dashboard → Cloud Agent → Environment → Secrets:

POCKET_MCP_API_KEY=<from PocketMCP app>
TAILSCALE_AUTH_KEY=<tskey-auth-...>
POCKET_MCP_TARGET=http://100.x.y.z:8080
NO_PROXY=127.0.0.1,localhost

Template: config/secrets.env.example

4. Cursor environment scripts

• Update script: scripts/environment-update.sh
• MCP config: config/mcp-android-phone.json.example (set your API key)

5. Test

bash scripts/check-setup.sh
bash scripts/start-gsm-access.sh
POCKET_MCP_URL=$POCKET_MCP_TARGET/mcp node scripts/gsm-api.mjs screen_state

First-time setup: docs/setup-guide.md

---

Testing strategy

The repo has three test layers, each covering the parts that can be checked automatically or safely:

1. Python unit tests — scripts/phone-http-proxy.py is tested with mocked urllib.request.urlopen calls. The tests cover GET/POST forwarding, header filtering, body forwarding, HTTP error propagation, and SOCKS5 setup. They do not need a real phone or network. The Codecov badge reflects this layer.
2. Node.js and shell static checks — bash -n / ShellCheck for every shell script, node --check and npm audit for the bridge, plus a smoke test that confirms the bridge exits when POCKET_MCP_API_KEY is missing.
3. Manual end-to-end phone test — Before any release I run bash scripts/check-setup.sh, start Tailscale, and call screen_state against the live phone. This layer requires Android + PocketMCP + a Tailscale tailnet and cannot run in CI, but it is the only way to validate the full cloud-agent → bridge → proxy → SOCKS5 → phone path.

---

What you get

• Cursor agent sees and controls your phone via MCP.
• Traffic uses Tailscale SOCKS5 — direct cloud → phone TCP often fails without it.
• Open bridge scripts + MCP stdio adapter — secrets in Cursor env, nothing hardcoded to one user.

---

What makes this different

Most phone-automation demos are either closed-source SaaS or require adb over USB. PhoneConnect is a small, auditable bridge that lets a Cursor Cloud Agent reach a phone through Tailscale without exposing the phone to the public internet. The moving parts are intentionally tiny: one Python HTTP proxy, one Node.js stdio bridge, and a few shell scripts.

Lessons learned

• Direct cloud → phone TCP usually fails. Carrier-grade NAT and firewalls make it hard for a cloud agent to hit a phone IP directly. Routing through a Tailscale SOCKS5 userspace proxy is the simplest reliable path.
• Keep the bridge stateless. The Node bridge only translates MCP stdio JSON to HTTP; it does not manage phone state. State lives in the phone and is inspected with screen_state after every action.
• Secrets belong in the environment. No keys are compiled into the scripts; the same repo works for any user who fills in config/secrets.env.example.
• Coverage is honest. The Codecov badge only covers the Python proxy. The Node bridge and shell scripts are checked with static analysis and manual smoke tests, not fake unit tests.

---

Architecture

Cursor MCP → bridge.mjs → http://127.0.0.1:18090/mcp (phone-http-proxy.py)
  → SOCKS5 127.0.0.1:1055 (Tailscale userspace)
  → http://YOUR_TAILSCALE_IP:8080 (PocketMCP on phone)

---

Repository layout

Path	Description
scripts/check-setup.sh	Validate secrets, Tailscale, phone reachability
scripts/start-gsm-access.sh	Start proxy + health check
scripts/environment-update.sh	Paste into Cursor Environment
mcp-bridge/bridge.mjs	MCP stdio ↔ PocketMCP HTTP
docs/setup-guide.md	Complete setup walkthrough
docs/memory/	Optional agent playbooks

---

Using the agent on your phone

Enable the Android phone MCP server in your cloud agent. After every phone action → call screen_state → verify → continue.

---

Requirements

Component	Requirement
Phone	Android + PocketMCP + Tailscale
Cloud	Cursor Cloud Agent environment
Network	Phone and agent on the same Tailscale tailnet
Secrets	API key + Tailscale auth key + POCKET_MCP_TARGET

---

Security

No public API in this repo — safety depends on Tailscale ACLs and secret handling. Never commit real keys; treat PocketMCP and Tailscale auth keys like root credentials for your phone.

See SECURITY.md for the security model, deployment guidance, and reporting.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature-name
5. Submit a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgments

• PocketMCP — Android automation API
• Tailscale — secure connectivity
• Cursor — Cloud Agents

---

📞 Support

For support and questions:

• Complete setup guide
• Create an issue on GitHub
• Security: see SECURITY.md

---

⭐ If this project helped you, please give it a star!