signal-mcp-server

# 📱 signal-mcp-server MCP Server for retrieving Signal messages using signal-export logic. ## 🎯 Overview This MCP server enables AI agents and tools to access Signal Desktop chat messages and attachments via the Model Context Protocol (MCP). ## 🛠️ Features - Retrieve Signal messages from your local Signal Desktop database - List all Signal chats with contact details and message counts - Filter messages by chat/contact name - Paginate through message history with offset and limit - Support for multiple operating systems (Windows, macOS, Linux) - Handle encrypted Signal databases ## 📋 Prerequisites - Python 3.13 or higher - UV package manager - Signal Desktop installed with existing message database - Node.js and npm (for MCP inspector tools) - Windows, macOS, or Linux operating system ### 1. Signal Desktop - **Official Download Page:** [https://signal.org/download/](https://signal.org/download/) - **Direct Download Links:** - [Windows](https://signal.org/download/windows/) - [Mac](https://signal.org/download/macos/) - [Linux (Debian-based)](https://signal.org/download/linux/) > **Note:** Signal Desktop requires Signal to be installed on your phone for initial setup. --- ### 2. Python - **Official Download Page:** [https://www.python.org/downloads/](https://www.python.org/downloads/) - **Direct Download for Python 3.13.5:** [Python 3.13.5 Release Page](https://www.python.org/downloads/release/python-3135/) - Download the installer for your OS (Windows, macOS, Linux) and follow the setup instructions. --- ### 3. UV (Python Package Manager) - **Official Documentation & Source:** [https://github.com/astral-sh/uv](https://github.com/astral-sh/uv) [UV Documentation](https://docs.astral.sh/uv/) - **Installation (Windows):** ```powershell irm https://astral.sh/uv/install.ps1 | iex ``` Or, using pip (if you already have Python and pip installed): ```powershell pip install uv ``` - **Installation (macOS/Linux):** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` - **More Info:** [UV Installation Guide](https://docs.astral.sh/uv/getting-started/installation/) ### 4. Claude Desktop - **Official Download Page:** [https://claude.ai/download](https://claude.ai/download) - Download the installer for your OS (Windows, macOS) and follow the setup instructions. ## 🚀 Installation Signal MCP Server 1. Clone the repository: ```powershell git clone https://github.com/stefanstranger/signal-mcp-server.git cd signal-mcp-server ``` 2. Create a virtual environment: ```powershell uv venv .venv --python 3.13 ``` 3. Activate the virtual environment: - **Windows PowerShell:** ```powershell .\.venv\Scripts\Activate.ps1 ``` - **macOS/Linux:** ```bash source .venv/bin/activate ``` 4. Install dependencies: ```powershell uv pip install fastmcp signal-export ``` ## ⚙️ Configuration ### 🔧 Claude Desktop Setup Usage with Claude Desktop Add the following to your claude_desktop_config.json file: ```json { "mcpServers": { "signal-mcp-server": { "type": "stdio", "command": "uv", "args": [ "run", "--with", "mcp[cli]", "--with", "signal-export", "mcp", "run", "C:\\Github\\signal-mcp-server\\server.py" ] } } } ``` ### Signal Data Directory The server automatically detects your Signal data directory based on your operating system: - **Windows**: `%APPDATA%\Signal` - **macOS**: `~/Library/Application Support/Signal` - **Linux**: `~/.config/Signal` (or Flatpak: `~/.var/app/org.signal.Signal/config/Signal`) ### Encryption If your Signal database is encrypted, you may need to provide: - `password`: Database password (if set) - `key`: Encryption key (if required) ## 🏃 Running the Server ### Start MCP Server ```powershell uv run .\server.py ``` ### Inspect MCP Server Using the MCP Inspector: ```powershell npx @modelcontextprotocol/inspector uv run --with mcp[cli] mcp run c://github//signal-mcp-server//server.py ``` Using mcptools: ```powershell mcptools web cmd /c "uv.exe run --with mcp[cli] --with signal-export mcp run c:\\github\\signal-mcp-server\\server.py" ``` ## 📖 Available Tools ### 1. `signal_list_chats` Lists all Signal chats with their details. **Parameters:** - `source_dir` (optional): Custom Signal data directory path - `password` (optional): Database password - `key` (optional): Encryption key - `include_empty` (optional): Include chats with no messages - `include_disappearing` (optional): Include disappearing messages **Example Response:** ```json [ { "name": "John Doe", "number": "+1234567890", "ServiceId": "abc123...", "total_messages": 150 } ] ``` ### 2. `signal_get_chat_messages` Retrieves messages from a specific chat by name. **Parameters:** - `chat_name` (required): Name of the chat contact - `limit` (optional): Maximum number of messages to return - `offset` (optional): Number of messages to skip (for pagination) - Other parameters same as `signal_list_chats` **Example Response:** ```json [ { "date": "2025-07-31T10:30:00", "sender": "John Doe", "body": "Hello! How are you?", "quote": "", "reactions": [], "attachments": [] } ] ``` ### 3. `signal_search_chat` Search for specific text within Signal chat messages. **Parameters:** - `chat_name` (required): Name of the chat to search within - `query` (required): Text to search for in message bodies - `limit` (optional): Maximum number of matching messages to return - `source_dir` (optional): Custom Signal data directory path - `password` (optional): Database password - `key` (optional): Encryption key - `include_empty` (optional): Include chats with no messages - `include_disappearing` (optional): Include disappearing messages **Example Response:** ```json [ { "date": "2025-07-31T10:30:00", "sender": "John Doe", "body": "Let's meet at the coffee shop tomorrow", "quote": "", "reactions": [], "attachments": [] } ] ``` ## 🎯 Available Prompts The server includes pre-built prompts for common analysis tasks: ### 1. `signal_summarize_chat_prompt` Generate a summary prompt for recent messages in a specific chat. ### 2. `signal_chat_topic_prompt` Generate a prompt to analyze discussion topics in a chat. ### 3. `signal_chat_sentiment_prompt` Generate a prompt to analyze message sentiment in a chat. ### 4. `signal_search_chat_prompt` Generate a search prompt for finding specific text in a chat. ## 💡 Usage Examples ### List all chats ``` "List all Signal chats please" ``` ### Get recent messages from a specific chat ``` "Show me the last 10 messages from the Family group chat" ``` ### Search for topics in a chat ``` "What are the main topics discussed in the Work Team chat?" ``` ### Summarize conversations ``` "Summarize the recent conversation with John Doe" ``` ### Search within a chat ``` "Search for messages containing 'meeting' in the Work Team chat" ``` ### Analyze chat sentiment ``` "Analyze the sentiment of recent messages with Sarah" ``` ## 🔒 Security & Privacy ⚠️ **Important**: This server provides access to your personal Signal messages. Please: - Only run this server locally - Never expose it to the internet - Be cautious about which AI agents you grant access - Consider the privacy of others in your conversations - Delete any exported data when no longer needed ## 🐛 Troubleshooting ### Common Issues 1. **"Signal database not found"** - Ensure Signal Desktop is installed - Check if the data directory path is correct - Verify you have read permissions 2. **"Database is encrypted"** - Signal databases may be encrypted on some systems - You may need to provide encryption credentials 3. **"No messages found"** - Verify the chat name is spelled correctly - Check if the chat has any messages - Try using `include_empty=True` parameter 4. **"Signal-MCP-Server does not want to start in Claude Desktop"** - Check if there are no other Python versions installed besides the recommended version 3.13. - You may need to uninstall older Python versions installed. ## 📚 References - [signal-export](https://github.com/carderne/signal-export) - [Model Context Protocol](https://modelcontextprotocol.io/) - [Create MCP Server](https://github.com/modelcontextprotocol/create-python-server) - [FastMCP](https://github.com/jlowin/fastmcp) - [MCP Tools](https://github.com/mcptools/mcptools) ## 🙏 Credits This project builds upon the excellent work of the [signal-export](https://github.com/carderne/signal-export) project by [Chris Arderne](https://github.com/carderne). The core logic for accessing and reading Signal Desktop databases is derived from and inspired by the signal-export library. I'm grateful for Chris his open-source contribution that made this MCP server possible. ## 📄 License MIT License ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## ⚖️ Disclaimer This tool is not affiliated with or endorsed by Signal. Use at your own risk and respect the privacy of your conversations.