From signal-mcp
This skill should be used when the user asks to "set up Signal", "install signal-cli", "register Signal account", "link Signal device", "configure SIGNAL_ACCOUNT", or when an MCP tool returns a `signal-cli not found` / `SIGNAL_ACCOUNT not set` / `unregistered account` error. Walks through installing signal-cli, picking between registering a new number and linking as a secondary device, completing verification, and configuring the plugin's environment variables.
How this skill is triggered — by the user, by Claude, or both
Slash command
/signal-mcp:signal-setupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provisions signal-cli and an account so the `signal-mcp` MCP server can run. It covers four phases: **diagnose**, **install**, **provision an account** (register *or* link), and **configure**. Stop at the first phase that resolves the user's blocker.
This skill provisions signal-cli and an account so the signal-mcp MCP server can run. It covers four phases: diagnose, install, provision an account (register or link), and configure. Stop at the first phase that resolves the user's blocker.
Before installing anything, call the MCP tool to see exactly what's missing:
signal_check_setup()
Interpret the returned error field:
| Error fragment | What's missing | Jump to |
|---|---|---|
signal-cli not found / binary is null | signal-cli is not installed | Phase 2 |
SIGNAL_ACCOUNT environment variable is not set | env var for plugin | Phase 4 |
is not registered with signal-cli | account exists but not provisioned (or wrong number) | Phase 3 |
ok: true | nothing to do | stop |
Run signal-cli --version directly only if the MCP tool itself is failing to launch (e.g., uv missing). For a one-shot diagnostic that doesn't need the MCP server at all, run scripts/check-install.sh from this skill — it prints PATH, signal-cli version, java version, and registered accounts.
Note on PATH: the MCP server inherits PATH from whatever shell launched Claude Code. If uv and signal-cli work in an interactive terminal but not in the MCP tool, ensure they're on PATH in the launching shell's profile (~/.zshrc, ~/.bashrc), not just in shell rc files.
signal-cli requires Java 21+. Recommend the platform-native install path; fall back to the tarball when no package exists. See references/install-platforms.md for full per-OS detail.
Common one-liners:
brew install signal-clitemurin-21-jre then download the official tarballpacman -S signal-clinix-shell -p signal-cli/opt/signal-cli, symlink into /usr/local/binAfter installing, re-run signal_check_setup(). If signal-cli exists at a non-PATH location, set SIGNAL_CLI_BIN to its absolute path instead of putting it on PATH.
Two flows. Ask the user which they want before running anything destructive.
If the user already has Signal on a phone and just wants Claude to send/receive on their behalf, link signal-cli as an additional device. No SMS, no captcha, no 7-day cooldowns. The primary phone stays in charge.
Steps:
signal-cli link -n "Claude (signal-mcp)" — prints a sgnl://linkdevice?... URI. With qrencode installed, pipe through it for a scannable QR (signal-cli link -n "..." | qrencode -t ansiutf8).signal-cli to print the registered phone number; that's the SIGNAL_ACCOUNT value for Phase 4.Detail and troubleshooting in references/linking.md.
Only when the user wants signal-cli to be the primary Signal device for a number — typically a fresh phone number used solely for automation. This will sign the user out of Signal on their phone if it's the same number; warn them.
Steps (full transcript and captcha link in references/registration.md):
signal-cli -a +<E164> register — Signal sends an SMS verification code. If rate-limited, ask the user to fetch a captcha token from https://signalcaptchas.org/registration/generate.html and re-run with --captcha "signalcaptcha://...".signal-cli -a +<E164> verify <SMS_CODE> — completes registration. If a registration lock PIN is required, append -p <PIN>.signal-cli -a +<E164> updateProfile --given-name "<Name>" — sets the profile name (Signal will warn on send if missing).The MCP server reads two env vars:
SIGNAL_ACCOUNT (required) — E.164 phone number of the provisioned account, e.g. +14155551212.SIGNAL_CLI_BIN (optional) — absolute path to the binary if it's not on PATH.Set these in the user's shell profile (~/.zshrc, ~/.bashrc) and export in the current shell so the MCP server picks them up on next launch:
export SIGNAL_ACCOUNT="+14155551212"
The plugin's .mcp.json already references these via ${SIGNAL_ACCOUNT} / ${SIGNAL_CLI_BIN}. Ask the user to restart Claude Code (or reload the plugin) so the MCP server picks up the new environment.
Verify:
signal_check_setup() → { ok: true, ... }
Then run a smoke test by asking the user for a username/number to send "hello" to, and call signal_send.
signal_check_setup
├── binary missing → Phase 2 (install)
├── account not set → Phase 4 (env var)
├── account not registered
│ ├── user has phone → Phase 3A (link as secondary)
│ └── user has bare # → Phase 3B (register primary)
└── ok=true → done
signal-cli link and re-scan.signal_get_user_status returns isRegistered: false. Check the username flow or confirm the contact actually has Signal.references/install-platforms.md — full install instructions for macOS, Debian/Ubuntu, RHEL/Fedora, Arch, Nix, and manual tarball.references/registration.md — register-as-primary flow including captcha and PIN handling.references/linking.md — link-as-secondary flow including QR generation and re-link.scripts/check-install.sh — one-shot diagnostic: prints PATH, signal-cli version, java version, registered accounts. Run when the MCP tool is unavailable.npx claudepluginhub alexey-max-fedorov/signal-mcp --plugin signal-mcpCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.