{"id":51118616,"url":"https://github.com/wexi/phone-mcp","last_synced_at":"2026-06-25T00:01:02.992Z","repository":{"id":364828692,"uuid":"1269365811","full_name":"wexi/phone-mcp","owner":"wexi","description":"Give your AI assistant senses on your phone over KDE Connect — an MCP server for camera, notifications, SMS, typing, media control, and file share. No adb.","archived":false,"fork":false,"pushed_at":"2026-06-14T17:48:51.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T18:14:21.536Z","etag":null,"topics":["android","anthropic","claude","claude-code","kde-connect","kdeconnect","llm-tools","mcp","model-context-protocol","phone"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wexi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T16:14:43.000Z","updated_at":"2026-06-14T17:48:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wexi/phone-mcp","commit_stats":null,"previous_names":["wexi/phone-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/wexi/phone-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wexi%2Fphone-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wexi%2Fphone-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wexi%2Fphone-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wexi%2Fphone-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wexi","download_url":"https://codeload.github.com/wexi/phone-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wexi%2Fphone-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34753781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","anthropic","claude","claude-code","kde-connect","kdeconnect","llm-tools","mcp","model-context-protocol","phone"],"created_at":"2026-06-25T00:01:02.197Z","updated_at":"2026-06-25T00:01:02.979Z","avatar_url":"https://github.com/wexi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phone-mcp — give your assistant senses on your phone\n\nGive an AI assistant senses on your **phone** over **KDE Connect** — eyes\n(camera), ears (notifications, now-playing), and a voice (SMS, typing, file\npush, media control) — for hands-off bench work and remote control. Works with\nany KDE Connect-paired device (developed and tested against a Pixel 9 Pro).\n\n![demo](demo.gif)\n\n*Above: real `kdeconnect.py` runs — status, a ping, and pulling the newest\ncamera photo (an oscilloscope on the bench) to the host, all over the stable\nKDE Connect link with no adb and no cable.*\n\nKDE Connect is the whole transport: a persistent, cert-pinned link held warm by\nthe `kdeconnectd` daemon. Pair once on the phone and it survives drops and\nreboots; each call is a fast local hop into the daemon — no rediscovery, no\ntoggling. (We deliberately do **not** use adb: it's flaky over Wireless\ndebugging and really an app-dev tool. Its only unique tricks — screencap of the\nphone display and a raw shell — aren't what this is for.)\n\nTwo entry points share one `KDEConnect` class:\n\n- **`kdeconnect.py`** — library + CLI.\n- **`pixel_mcp.py`** — MCP server exposing the moves as `kde_*` tools.\n\n## Setup\n\n- `kdeconnect-cli` and `gdbus` on PATH (KDE Connect package, here 23.08).\n- The MCP server needs the `mcp` Python package (present in `~/PY3`).\n\nPair once: on the **phone**, open **KDE Connect**, join the home Wi-Fi, and\naccept the pairing request:\n\n```bash\nkdeconnect-cli --pair            # then tap Accept on the phone\npython3 kdeconnect.py status     # sanity check: paired?, battery, signal\n```\n\nBy default the first paired+reachable KDE Connect device is used. Targeting and\npaths are environment-overridable: `KDECONNECT_NAME` (pin a device by name),\n`KDECONNECT_DEVICE` (pin by id), `KDECONNECT_CLI`, `PIXEL_PULL_DIR` (default\n`~/Pictures/pixel`).\n\n## Standalone — CLI\n\n| Verb | Purpose |\n|---|---|\n| `status` | device snapshot — paired?, reachable?, battery, connectivity |\n| `devices` | list paired/reachable KDE Connect devices |\n| `pair` | request pairing (Accept on the phone) |\n| `pull` | pull newest (or named) camera photo to the host (over SFTP) |\n| `photos` | list newest camera files (name, size, mtime) |\n| `photo` | open the phone camera, wait for a shot, transfer it (needs camera permission) |\n| `notifications` | list the phone's active notifications |\n| `sms` | send an SMS (`message destination`) |\n| `type` | type text into the phone's focused field (remote keyboard) |\n| `share` | push a local file/URL to the phone |\n| `clipboard` | send the desktop clipboard to the phone |\n| `playing` | current media track + transport state |\n| `players` | list available media players |\n| `media` | media control (`play`/`pause`/`playpause`/`next`/`previous`/`stop`) |\n| `ping` | buzz the phone (optional message) |\n| `ring` | ring the phone loudly to locate it |\n\n```bash\npython3 kdeconnect.py status\npython3 kdeconnect.py pull                    # newest camera photo -\u003e ~/Pictures/pixel\npython3 kdeconnect.py photos -n 5\npython3 kdeconnect.py notifications\npython3 kdeconnect.py sms \"on my way\" +15551234567\npython3 kdeconnect.py type \"hello from the desktop\"\npython3 kdeconnect.py share ~/Pictures/x.png\npython3 kdeconnect.py ring\n```\n\n**Two ways to get \"eyes\":** `pull` grabs a photo you *already* shot (reads the\nphone's camera folder over the SFTP plugin — the reliable everyday path, \"took\na snap → look at it\"). `photo` triggers a *fresh* on-demand capture by opening\nthe camera remotely; it needs the KDE Connect app to have Android **camera\npermission** granted.\n\nAs a library:\n\n```python\nfrom kdeconnect import KDEConnect\nkc = KDEConnect()\nprint(kc.status())\nlocal = kc.photo()         # opens camera, returns the saved Path\nkc.send_sms(\"hi\", \"+15551234567\")\n```\n\n`status` / `battery` / `connectivity` are read from the `kdeconnectd` D-Bus\ninterface (via `gdbus`), since `kdeconnect-cli` has no flag for them; all\nactions go through `kdeconnect-cli`.\n\n## As an MCP server\n\n`pixel_mcp.py` exposes the moves as MCP tools over stdio. Register with Claude\nCode (or any MCP client):\n\n```bash\nclaude mcp add pixel --scope user -- python3 /path/to/phone-mcp/pixel_mcp.py\n# pin a specific paired device by name:\nclaude mcp add pixel --scope user --env KDECONNECT_NAME=\"My Phone\" \\\n  -- python3 /path/to/phone-mcp/pixel_mcp.py\n```\n\nTools: `kde_status`, `kde_pull`, `kde_photos`, `kde_photo`, `kde_notifications`,\n`kde_send_sms`, `kde_send_text`, `kde_share`, `kde_clipboard`, `kde_ls`,\n`kde_get`, `kde_put`, `kde_rm`, `kde_now_playing`, `kde_media_control`,\n`kde_media_players`, `kde_ping`, `kde_ring`. The device snapshot is also a\nread-only resource, `pixel://status`.\n\n`kde_ls` / `kde_get` / `kde_put` / `kde_rm` are general file transfer over the\nSFTP mount — list any directory, pull/push any file by path (relative to the\nphone's internal storage), and delete. `kde_rm` is irreversible (no trash).\n\n`kde_photo` returns the captured photo as an MCP **image**, so the model sees\nthe picture rather than only a file path. Every call rides the always-warm\ndaemon link.\n\n## Permissions\n\nA few plugins need Android permissions before their tools work: Notification\nsync (`kde_notifications` + the media tools), Camera (`kde_photo`), Receive\nremote keypresses (`kde_send_text`), and the SMS grants. Grant them by hand in\nthe KDE Connect app (tap the desktop → \"Some Plugins need permissions\"), **or**\nrun the optional one-time adb bootstrap:\n\n```bash\nscripts/setup-permissions.sh          # needs adb + a reachable device\nADB_SERIAL=\u003cserial\u003e scripts/setup-permissions.sh   # pick one of several devices\n```\n\nIt's idempotent and non-destructive (it won't change your active keyboard). adb\nis bootstrap-only here — the MCP transport stays KDE Connect. SMS, ping, ring,\nshare, SFTP pull/photos, and status/battery need no extra grants.\n\n## Gotchas\n\n- **KDE Connect must be open on the phone, on the home Wi-Fi, and paired** with\n  this desktop, or calls report not-reachable. Pairing is one-time and persists\n  across reboots.\n- **`kde_photo` blocks** until the user takes the shot — tell them the camera\n  is open and to snap it.\n- **No phone-screen screencap and no raw shell** — KDE Connect can't do either.\n  The camera is the eyes here, not the phone's own display.\n- SMS goes over the phone's **real cellular line** — real messages, real\n  recipients.\n- `kde_photo` saves to `~/Pictures/pixel` (override `PIXEL_PULL_DIR`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwexi%2Fphone-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwexi%2Fphone-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwexi%2Fphone-mcp/lists"}