{"id":29963214,"url":"https://github.com/piebro/signal-mcp-client","last_synced_at":"2025-08-04T00:34:28.399Z","repository":{"id":287773748,"uuid":"956768564","full_name":"piebro/signal-mcp-client","owner":"piebro","description":"An MCP client that uses signal for sending and receiving messages.","archived":false,"fork":false,"pushed_at":"2025-04-30T15:53:04.000Z","size":2635,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-22T18:48:43.192Z","etag":null,"topics":["mcp","mcp-client","signal"],"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/piebro.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}},"created_at":"2025-03-28T20:37:43.000Z","updated_at":"2025-07-08T15:35:28.000Z","dependencies_parsed_at":"2025-04-13T21:27:01.388Z","dependency_job_id":"131cf657-0f34-4c34-b2ed-51d4c70c6690","html_url":"https://github.com/piebro/signal-mcp-client","commit_stats":null,"previous_names":["piebro/signal-mcp-client"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/piebro/signal-mcp-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fsignal-mcp-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fsignal-mcp-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fsignal-mcp-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fsignal-mcp-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piebro","download_url":"https://codeload.github.com/piebro/signal-mcp-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piebro%2Fsignal-mcp-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268634143,"owners_count":24281904,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"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":["mcp","mcp-client","signal"],"created_at":"2025-08-04T00:34:27.762Z","updated_at":"2025-08-04T00:34:28.388Z","avatar_url":"https://github.com/piebro.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Signal MCP Client\n\nAn MCP (Model Context Protocol) client that uses Signal for sending and receiving messages.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/piebro/signal-mcp-client/main/assets/settings_chat_screenshot.png\" width=\"30%\" style=\"padding: 1% 1% 1% 1%; vertical-align: middle;\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/piebro/signal-mcp-client/main/assets/edit_image_chat_screenshot.png\" width=\"30%\" style=\"padding: 1% 1% 1% 1%; vertical-align: middle;\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/piebro/signal-mcp-client/main/assets/generate_image_chat_screenshot.png\" width=\"30%\" style=\"padding: 1% 1% 1% 1%; vertical-align: middle;\"\u003e\n\u003c/p\u003e\n\n## Setup and start the Signal Chat Bot\n\nThese Instructions are for Ubuntu Linux. With some minor modification this should also work on other Linux Distros, Mac or Windows.\nI recommend to use an extra phone number for the bot, so you don't have to use your own.\n\n1. Install [uv](https://docs.astral.sh/uv/) and [podman](https://podman.io/):\n    ```bash\n    sudo apt install podman\n    curl -LsSf https://astral.sh/uv/install.sh | sh\n    ```\n2. Start the [Signal CLI Rest Server](https://github.com/bbernhard/signal-cli-rest-api) container:\n    ```bash\n    mkdir -p $HOME/.local/share/signal-api\n    podman run \\\n        --name signal-cli-api \\\n        --replace \\\n        -p 8080:8080 \\\n        -v $HOME/.local/share/signal-api:/home/.local/share/signal-cli \\\n        -e 'MODE=json-rpc' \\\n        docker.io/bbernhard/signal-cli-rest-api:latest-dev\n    ```\n3. Connect the signal-cli-rest-api container to your signal account by opening this link and scanning the QR code:\n    ```\n    http://localhost:8080/v1/qrcodelink?device_name=signal-api\n    ```\n4. Create a config.json with your mcp servers. For example for testing you can use:\n    ```bash\n    cat \u003c\u003c EOF \u003e config.json\n    {\n        \"servers\": [{\n            \"name\": \"echo-mcp-server-for-testing\",\n            \"command\": \"uvx\",\n            \"args\": [\"echo-mcp-server-for-testing\"],\n            \"env\": {\"SECRET_KEY\": \"123456789\"}\n        }]\n    }\n    EOF\n    ```\n5. Create a session directory for saving the message history, images, videos and settings for each user and start the MCP client:\n    ```bash\n    export ANTHROPIC_API_KEY='your-key'\n    export SIGNAL_PHONE_NUMBER='+1234567890'\n    export FAL_KEY='your-key' # optional for transcribing voice messages\n\n    uvx signal-mcp-client \\\n        --config config.json \\\n        --session-save-dir /absolute/path/to/session/dir \\\n        --available-models claude-3-7-sonnet-latest claude-3-5-haiku-latest \\\n        --default-model-name claude-3-7-sonnet-latest \\\n        --default-system-prompt \"\" \\\n        --default-llm-chat-message-context-limit 50\n    ```\n\n## Adding MCP Server\n\nAdd the MCP server in the `config.json` file.\n\nHere are some example servers I use:\n- [vlc-mcp-server](https://github.com/piebro/vlc-mcp-server): An MCP Server to play and control local movies using VLC.\n- [fal-ai-mcp-server](https://github.com/piebro/fal-ai-mcp-server): An MCP Server to use the fal.ai APIs to generate images and videos. \n\n## Contributing\n\nContributions to this project are welcome. Feel free to report bugs, suggest ideas, or create merge requests.\n\n## Development\n\n### Running from source\n\n1. Clone the repo `git clone git@github.com:piebro/signal-mcp-client.git`.\n2. Go into the root dir `cd signal-mcp-client`.\n3. Run the MCP client:\n    ```bash\n    export ANTHROPIC_API_KEY='your-key'\n    export SIGNAL_PHONE_NUMBER='+1234567890'\n    export FAL_API_KEY='your-key' # optional for transcribing voice messages\n    # additional optional environment variables:\n    export SIGNAL_WS_BASE_URL=\"ws://localhost:8080\"\n    export SIGNAL_HTTP_BASE_URL=\"http://localhost:8080\" \n    export CLIENT_LOG_LEVEL=\"DEBUG\"\n    export SERVER_LOG_LEVEL=\"DEBUG\"\n    # you can also use a .env file in the root directory to set the environment variables\n\n    uv run signal_mcp_client/main.py \\\n        --config config.json \\\n        --session-save-dir /absolute/path/to/session/dir \\\n        --available-models claude-3-7-sonnet-latest claude-3-5-haiku-latest \\\n        --default-model-name claude-3-7-sonnet-latest \\\n        --default-system-prompt \"\" \\\n        --default-llm-chat-message-context-limit 50\n    ```\n\n### Formatting and Linting\n\nThe code is formatted and linted with ruff:\n\n```bash\nuv run ruff format\nuv run ruff check --fix\n```\n\n### Building with uv\n\nBuild the package using uv:\n\n```bash\nuv build\n```\n\n### Releasing a New Version\n\nTo release a new version of the package to PyPI, create and push a new Git tag:\n\n```bash\ngit tag v0.2.0\ngit push origin v0.2.0\n```\n\n## Running as a Systemd Service\n\nTo 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.\nUser services run under your specific user account.\n\nThis setup assumes that you have completed the setup steps and your project is located at `/home/$USER/signal-mcp-client`.\n\n1. Enable User Lingering to keep your user session active after logging out.\n    ```bash\n    sudo loginctl enable-linger $USER\n    ```\n\n2. Create Systemd Service Directory\n    ```bash\n    mkdir -p /home/$USER/.config/systemd/user/\n    ```\n\n3. Create Service File for Signal REST API \n    ```bash\n    cat \u003c\u003c EOF \u003e \"/home/$USER/.config/systemd/user/signal-cli-rest-api.service\"\n    [Unit]\n    Description=Signal CLI REST API Container\n    After=network.target\n    Wants=network-online.target\n\n    [Service]\n    Environment=\"XDG_RUNTIME_DIR=/run/user/%U\"\n    Environment=\"DBUS_SESSION_BUS_ADDRESS=unix:path=%t/bus\"\n    SyslogIdentifier=signal-cli-rest-api\n    Restart=on-failure\n    RestartSec=30\n\n    ExecStartPre=-/usr/bin/podman stop signal-cli-api\n    ExecStartPre=-/usr/bin/podman rm signal-cli-api\n\n    ExecStart=/usr/bin/podman run --name signal-cli-api \\\\\n        -p 127.0.0.1:8080:8080 \\\\\n        --replace \\\\\n        -v /home/$USER/.local/share/signal-api:/home/.local/share/signal-cli \\\\\n        -e MODE=json-rpc \\\\\n        docker.io/bbernhard/signal-cli-rest-api:latest\n\n    ExecStop=/usr/bin/podman stop signal-cli-api\n\n    [Install]\n    WantedBy=default.target\n    EOF\n    ```\n\n4. Create Service File for Signal MCP Client\n    ```bash\n    cat \u003c\u003c EOF \u003e \"/home/$USER/.config/systemd/user/signal-mcp-client.service\"\n    [Unit]\n    Description=Signal MCP Client Application\n    After=network.target signal-cli-rest-api.service\n    Wants=signal-cli-rest-api.service\n\n    [Service]\n    Environment=\"ANTHROPIC_API_KEY=your-key\" \n    Environment=\"SIGNAL_PHONE_NUMBER=+1234567890\"\n    # Environment=\"FAL_KEY=your-key\"\n    # Environment=\"SIGNAL_WS_BASE_URL=ws://127.0.0.1:8080\"\n    # Environment=\"SIGNAL_HTTP_BASE_URL=http://127.0.0.1:8080\" \n    # Environment=\"CLIENT_LOG_LEVEL=INFO\"\n    # Environment=\"SERVER_LOG_LEVEL=INFO\"\n    SyslogIdentifier=signal-mcp-client\n\n    Restart=on-failure\n    RestartSec=30\n\n    ExecStart=/home/$USER/.local/bin/uvx signal-mcp-client \\\n        --config config.json \\\n        --session-save-dir /home/$USER/sessions \\\n        --available-models claude-3-7-sonnet-latest claude-3-5-haiku-latest \\\n        --default-model-name claude-3-7-sonnet-latest \\\n        --default-system-prompt \"\" \\\n        --default-llm-chat-message-context-limit 50\n\n    [Install]\n    WantedBy=default.target\n    EOF\n    ```\n\n5. Enable and Start the Services\n    ```bash\n    systemctl --user daemon-reload\n\n    systemctl --user enable signal-cli-rest-api.service\n    systemctl --user enable signal-mcp-client.service\n\n    systemctl --user start signal-cli-rest-api.service\n    systemctl --user start signal-mcp-client.service\n    ```\n\n6. Check Service Status and Logs\n    ```bash\n    systemctl --user status signal-cli-rest-api.service\n    systemctl --user status signal-mcp-client.service\n\n    journalctl --user -u signal-cli-rest-api.service -f\n    journalctl --user -u signal-mcp-client.service -f\n    ```\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiebro%2Fsignal-mcp-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiebro%2Fsignal-mcp-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiebro%2Fsignal-mcp-client/lists"}