signal

This MCP server enables AI agents and tools to access and analyze your Signal Desktop messages and attachments by leveraging the signal-export logic. It exposes commands that let you list Signal chats, fetch messages from a specific chat, and search within chats. The available tools include signal_list_chats for listing chats with metadata, signal_get_chat_messages to retrieve messages from a chosen chat (with optional pagination), and signal_search_chat to find messages containing specific text within a chat. You can invoke these tools through MCP clients (e.g., MCP Inspector or mcptools) to integrate Signal data into your AI workflows.

To use the server, run it via UV as shown in the installation guide, or connect through an MCP inspector which wraps the UV-based CLI into a structured MCP interface. Once running, point your MCP client or Claude Desktop integration at the server to query chats, read messages, or perform targeted searches. The server handles multiple OS environments and can decrypt and access the local Signal database when provided with the necessary credentials and data directory path.

Prerequisites

• Python 3.13 or higher
• UV Python package manager
• Signal Desktop installed with an existing message database
• Node.js and npm (for MCP inspector tools)
• Windows, macOS, or Linux operating system

Step 1: Clone the repository

git clone https://github.com/stefanstranger/signal-mcp-server.git
cd signal-mcp-server

Step 2: Set up a Python virtual environment (using UV as shown in the guide)

uv venv .venv --python 3.13

Step 3: Activate the virtual environment

• Windows PowerShell:

.\.venv\Scripts\Activate.ps1

• macOS/Linux:

source .venv/bin/activate

Step 4: Install dependencies

uv pip install fastmcp signal-export

Step 5: Run the MCP server (example)

uv run .\server.py

Notes:

• Ensure Signal Desktop is installed and you know the location of your Signal data directory.
• If the Signal database is encrypted, you may need to provide a password and/or encryption key via configuration or runtime options depending on your setup.

Tips and common considerations:

• Encryption: If your Signal database is encrypted, you may need to provide password and/or encryption key to access messages.
• Signal data directory detection: The server auto-detects the data directory based on the OS, but you can override by supplying a custom source_dir when calling tools.
• Inspector tooling: For MCP inspection, you can use the MCP Inspector or mcptools to connect to the UV-based server. Ensure your environment paths are correct when invoking commands.
• Security: This server provides access to personal messages. Run locally and restrict access to trusted AI agents. Do not expose the server to the public internet.
• Troubleshooting: Common issues include missing Signal data, incorrect data path, or encrypted databases without credentials. Verify file permissions and paths, and ensure UV and Python dependencies are properly installed.