# Buddy phone tools

Buddy phone tools is an MCP server for Claude Code that connects an agent to an Android phone through Buddy. It runs when the agent needs to inspect the display or control an app.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 314 repo stars
- Author: ghorbelhamdi
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ghorbelhamdi/buddy-android/tree/HEAD/mcp-bridge
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/buddy-phone-tools

## What it does

Buddy phone tools forwards MCP requests to the Buddy app on an Android phone. The agent can inspect the display, tap controls, enter text, scroll, and launch apps. It can also request screenshots and notifications.

The bridge starts as a command over stdio and needs Node 18+ plus the `BUDDY_TOKEN` shown in Buddy’s settings. Buddy must be installed on the phone. Since the app listens only on `127.0.0.1`, run the bridge on that phone, for example in Termux.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `BUDDY_TOKEN`, `BUDDY_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env BUDDY_TOKEN=<BUDDY_TOKEN> --env BUDDY_URL=<BUDDY_URL> --transport stdio mcp-bridge -- npx -y buddy-phone-bridge
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add mcp-bridge --env BUDDY_TOKEN=<BUDDY_TOKEN> --env BUDDY_URL=<BUDDY_URL> -- npx -y buddy-phone-bridge
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-bridge": {
            "command": "npx",
            "args": [
                "-y",
                "buddy-phone-bridge"
            ],
            "env": {
                "BUDDY_TOKEN": "<BUDDY_TOKEN>",
                "BUDDY_URL": "<BUDDY_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-bridge": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "buddy-phone-bridge"
            ],
            "env": {
                "BUDDY_TOKEN": "<BUDDY_TOKEN>",
                "BUDDY_URL": "<BUDDY_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e BUDDY_TOKEN=<BUDDY_TOKEN> -e BUDDY_URL=<BUDDY_URL> mcp-bridge npx -y buddy-phone-bridge
```
Replace <…> with your own values

## When to use it
- inspect what is shown on an Android display
- tap an interface control or enter text
- scroll a page and launch an app
- retrieve a phone screenshot or its notifications

## Example prompts
- Read my phone screen and summarize what is open.
- Launch the needed app on my phone.
- Scroll down the page and enter text in the active field.

## Similar
- [webup-buddy-reroll](https://affpapa.org/en/nevibecode/skills/webup-buddy-reroll.md) — skill · 409 installs
- [phone_wait](https://affpapa.org/en/nevibecode/prompts/phone-wait.md) — prompt · ★ 9488 repo stars
- [phone-harness](https://affpapa.org/en/nevibecode/skills/phone-harness.md) — skill · ★ 567 repo stars
- [buddy](https://affpapa.org/en/nevibecode/skills/buddy.md) — skill · 1500 installs
- [phone_list_apps](https://affpapa.org/en/nevibecode/prompts/phone-list-apps.md) — prompt · ★ 9488 repo stars
- [Sms Gateway using your phone](https://affpapa.org/en/nevibecode/mcp/sms-gateway-using-your-phone.md) — MCP server · 1800 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
