Signal Mcp Client

Signal MCP Client

An MCP (Model Context Protocol) client that uses Signal for sending and receiving messages.

Setup and start the Signal Chat Bot

These Instructions are for Ubuntu Linux. With some minor modification this should also work on other Linux Distros, Mac or Windows. I recommend to use an extra phone number for the bot, so you don't have to use your own.

1. Install uv and podman:

``bash sudo apt install podman curl -LsSf https://astral.sh/uv/install.sh | sh ``

1. Start the Signal CLI Rest Server container:

``bash mkdir -p $HOME/.local/share/signal-api podman run \ --name signal-cli-api \ --replace \ -p 8080:8080 \ -v $HOME/.local/share/signal-api:/home/.local/share/signal-cli \ -e 'MODE=json-rpc' \ docker.io/bbernhard/signal-cli-rest-api:latest-dev ``

1. Connect the signal-cli-rest-api container to your signal account by opening this link and scanning the QR code:

`` http://localhost:8080/v1/qrcodelink?device_name=signal-api ``

1. Create a config.json with your mcp servers. For example for testing you can use:

``bash cat config.json { "servers": [{ "name": "echo-mcp-server-for-testing", "command": "uvx", "args": ["echo-mcp-server-for-testing"], "env": {"SECRET_KEY": "123456789"} }] } EOF ``

1. Create a session directory for saving the message history, images, videos and settings for each user and start the MCP client:

```bash export ANTHROPICAPIKEY='your-key' export SIGNALPHONENUMBER='+1234567890' export FAL_KEY='your-key' # optional for transcribing voice messages

uvx signal-mcp-client \ --config config.json \ --session-save-dir /absolute/path/to/session/dir \ --available-models claude-3-7-sonnet-latest claude-3-5-haiku-latest \ --default-model-name claude-3-7-sonnet-latest \ --default-system-prompt "" \ --default-llm-chat-message-context-limit 50 ```

Adding MCP Server

Add the MCP server in the config.json file.

Here are some example servers I use:

• vlc-mcp-server: An MCP Server to play and control local movies using VLC.
• fal-ai-mcp-server: An MCP Server to use the fal.ai APIs to generate images and videos.

Contributing

Contributions to this project are welcome. Feel free to report bugs, suggest ideas, or create merge requests.

Development

Running from source

1. Clone the repo git clone git@github.com:piebro/signal-mcp-client.git.
2. Go into the root dir cd signal-mcp-client.
3. Run the MCP client:

```bash export ANTHROPICAPIKEY='your-key' export SIGNALPHONENUMBER='+1234567890' export FALAPIKEY='your-key' # optional for transcribing voice messages # additional optional environment variables: export SIGNALWSBASEURL="ws://localhost:8080" export SIGNALHTTPBASEURL="http://localhost:8080" export CLIENTLOGLEVEL="DEBUG" export SERVERLOGLEVEL="DEBUG" # you can also use a .env file in the root directory to set the environment variables

uv run signalmcpclient/main.py \ --config config.json \ --session-save-dir /absolute/path/to/session/dir \ --available-models claude-3-7-sonnet-latest claude-3-5-haiku-latest \ --default-model-name claude-3-7-sonnet-latest \ --default-system-prompt "" \ --default-llm-chat-message-context-limit 50 ```

Formatting and Linting

The code is formatted and linted with ruff:

uv run ruff format
uv run ruff check --fix

Building with uv

Build the package using uv:

uv build

Releasing a New Version

To release a new version of the package to PyPI, create and push a new Git tag:

git tag v0.2.0
git push origin v0.2.0

Running as a Systemd Service

To ensure the Signal REST API and the MCP Client run automatically on boot and restart if they fail, you can set them up as systemd user services. User services run under your specific user account.

This setup assumes that you have completed the setup steps and your project is located at /home/$USER/signal-mcp-client.

1. Enable User Lingering to keep your user session active after logging out.

``bash sudo loginctl enable-linger $USER ``

1. Create Systemd Service Directory

``bash mkdir -p /home/$USER/.config/systemd/user/ ``

1. Create Service File for Signal REST API

```bash cat "/home/$USER/.config/systemd/user/signal-cli-rest-api.service" [Unit] Description=Signal CLI REST API Container After=network.target Wants=network-online.target

[Service] Environment="XDGRUNTIMEDIR=/run/user/%U" Environment="DBUSSESSIONBUS_ADDRESS=unix:path=%t/bus" SyslogIdentifier=signal-cli-rest-api Restart=on-failure RestartSec=30

ExecStartPre=-/usr/bin/podman stop signal-cli-api ExecStartPre=-/usr/bin/podman rm signal-cli-api

ExecStart=/usr/bin/podman run --name signal-cli-api \\ -p 127.0.0.1:8080:8080 \\ --replace \\ -v /home/$USER/.local/share/signal-api:/home/.local/share/signal-cli \\ -e MODE=json-rpc \\ docker.io/bbernhard/signal-cli-rest-api:latest

ExecStop=/usr/bin/podman stop signal-cli-api

[Install] WantedBy=default.target EOF ```

1. Create Service File for Signal MCP Client

```bash cat "/home/$USER/.config/systemd/user/signal-mcp-client.service" [Unit] Description=Signal MCP Client Application After=network.target signal-cli-rest-api.service Wants=signal-cli-rest-api.service

[Service] Environment="ANTHROPICAPIKEY=your-key" Environment="SIGNALPHONENUMBER=+1234567890" # Environment="FALKEY=your-key" # Environment="SIGNALWSBASEURL=ws://127.0.0.1:8080" # Environment="SIGNALHTTPBASEURL=http://127.0.0.1:8080" # Environment="CLIENTLOGLEVEL=INFO" # Environment="SERVERLOG_LEVEL=INFO" SyslogIdentifier=signal-mcp-client

Restart=on-failure RestartSec=30

ExecStart=/home/$USER/.local/bin/uvx signal-mcp-client \ --config config.json \ --session-save-dir /home/$USER/sessions \ --available-models claude-3-7-sonnet-latest claude-3-5-haiku-latest \ --default-model-name claude-3-7-sonnet-latest \ --default-system-prompt "" \ --default-llm-chat-message-context-limit 50

[Install] WantedBy=default.target EOF ```

1. Enable and Start the Services

```bash systemctl --user daemon-reload

systemctl --user enable signal-cli-rest-api.service systemctl --user enable signal-mcp-client.service

systemctl --user start signal-cli-rest-api.service systemctl --user start signal-mcp-client.service ```

1. Check Service Status and Logs

```bash systemctl --user status signal-cli-rest-api.service systemctl --user status signal-mcp-client.service

journalctl --user -u signal-cli-rest-api.service -f journalctl --user -u signal-mcp-client.service -f ```

License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: piebro
• Source: piebro/signal-mcp-client
• License: MIT

Install and usage instructions live in the source repository linked above.