claude-phone MCP
A desk SIP phone rings from a Claude Code session, and your voice on an extension is typed into the right session.
- 96 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Hooks in the global Claude Code settings see the start, end and every prompt of each session
- The daemon types recognized speech into iTerm2 and gets macOS permission to control it
- SIP and ElevenLabs secrets sit in the keychain and reply text goes to ElevenLabs when cloud voice is chosen
Install
- Works in
Manual install
claude mcp add --scope user claude-phone -- "$PWD/.venv/bin/phone" mcpRun from the repository folder after building the Python environment; four hooks in `~/.claude/settings.json` are also required.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Hooks in the global Claude Code settings see the start, end and every prompt of each session
- The daemon types recognized speech into iTerm2 and gets macOS permission to control it
- SIP and ElevenLabs secrets sit in the keychain and reply text goes to ElevenLabs when cloud voice is chosen
This is third-party code. Review the repository files before installing.
What it does
claude-phone turns a desk phone into a voice line to Claude Code sessions on a Mac. An agent calls the `call_<name>` tool: the phone rings with `repo/branch` as caller ID and the spoken answer returns to the agent as the tool result. `notify_<name>` reads a short announcement and hangs up, `transfer_call` puts you through to another session. The other direction works by dialing an extension: every live session gets a number from 301 to 399, and the words you say are typed into that session's iTerm2 tab. Unanswered questions pile up in voicemail. Everything runs locally: the Asterisk phone exchange, whisper.cpp speech recognition, macOS `say` or ElevenLabs for speech and a small Python daemon.
Who it is for. People who run several Claude Code sessions on a Mac with iTerm2 and want to answer agents by voice without sitting at the keyboard.
Good fit when
- A long task runs in the background while you are away from the desk: the agent rings when it needs a decision.
- Several sessions share one channel, and an extension reaches the one you want.
- An agent has finished and a short spoken announcement on the handset is enough.
- An answer is easier to dictate: speech is recognized locally and typed into the session.
Not a fit when
- You are on Windows, Linux or an Intel Mac: there are no instructions, the setup relies on iTerm2, `say`, the keychain and launchd.
- There is no SIP phone and no wish to run Asterisk: voice input will not repay the setup.
- Claude Code runs outside iTerm2, because words are typed through its tabs.
Example request
Ring me when the tests finish and ask whether to ship the branch.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
ELEVENLABS_API_KEYsecret- ElevenLabs key for cloud voices; the macOS voice is the default.
Limitations
Apple Silicon only (M1 or later): everything is built on macOS. iTerm2, Homebrew, Python 3.12 or newer, the Xcode command line tools to build Asterisk and about 1 GB for the speech model downloaded on first start are required. The author tested a Yealink T31P, other SIP phones are untested, the free Linphone works for trying it out. ElevenLabs and ntfy for push notifications are optional. Hooks are written into the global `~/.claude/settings.json` and the snippet for `CLAUDE.md` is added by hand.
How to disable. Stop the launchd services, remove the MCP server with `claude mcp remove claude-phone` and delete the four hooks from `~/.claude/settings.json`. The `~/.claude-phone` folder is erased by hand.
FAQ
Does the voice leave the Mac?
No, speech is recognized locally with whisper.cpp. Only text goes out to ElevenLabs if you pick that voice, and missed-call pushes if you set them up.
Which phone do I need?
A SIP phone on the same network as the Mac. The author built it on a Yealink T31P, which is powered over the network cable. The free Linphone app works for a trial.
How does an agent get my answer to a call?
The agent calls `call_<name>`, for example `call_sam` when `owner_name = "Sam"`. The phone rings and what you say comes back as the tool result.
What happens to unanswered questions?
They go to voicemail and the message light turns on. Press Message and answer each one: the answers are typed into the asking sessions.
How many sessions can be on the line?
Extensions 301–399 go to live Claude Code sessions, `phone list` shows them. Dialing 0 reaches the operator, 9 types your message into every session at once.
Discussion
No questions or reviews yet.
Related
MCP serversA Claude Code plugin that phones you when the agent has finished, is stuck, or needs a decision
A macOS toolkit on top of Claude Code: standing worker chats, a voice call with your session and Workers and Spaces panes.
Claudette runs several Claude Code sessions in parallel, each in its own git worktree, from a window or the console
A Claude Code channel plugin and phone PWA: a private chat with an agent session through your own server, no chat service
A phone as a remote for Claude Code, Codex and OpenCode: watch the agent work and approve actions while it stays on your PC.
A bridge server and mobile app that opens your computer's Claude Code and Codex sessions as a chat on your phone
README in short
The project builds a phone line between you and Claude Code sessions: the Asterisk exchange, speech recognition, text to speech, MCP call tools and session hooks. The README walks through the Mac install and phone setup.