📱 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/

• Direct Download Links:

  • Windows

  • Mac

  • Linux (Debian-based)

Note: Signal Desktop requires Signal to be installed on your phone for initial setup.

2. Python

• Official Download Page:
  https://www.python.org/downloads/

• Direct Download for Python 3.13.5:
  Python 3.13.5 Release Page

• 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
  UV Documentation

• Installation (Windows):

  irm https://astral.sh/uv/install.ps1 | iex

  Or, using pip (if you already have Python and pip installed):

  pip install uv

• Installation (macOS/Linux):

  curl -LsSf https://astral.sh/uv/install.sh | sh

• More Info:
  UV Installation Guide

4. Claude Desktop

• Official Download Page:
  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:

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

2. Create a virtual environment:

   uv venv .venv --python 3.13

3. Activate the virtual environment:

   • Windows PowerShell:

     .\.venv\Scripts\Activate.ps1

   • macOS/Linux:

     source .venv/bin/activate

4. Install dependencies:

   uv pip install fastmcp signal-export

⚙️ Configuration

🔧 Claude Desktop Setup

Usage with Claude Desktop Add the following to your claude_desktop_config.json file:

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

Inspect MCP Server

Using the MCP Inspector:

Using mcptools:

📖 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:

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:

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:

🎯 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

Get recent messages from a specific chat

Search for topics in a chat

Summarize conversations

Search within a chat

Analyze chat sentiment

🔒 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

• Model Context Protocol

• Create MCP Server

• FastMCP

• MCP Tools

🙏 Credits

This project builds upon the excellent work of the signal-export project by Chris Arderne. 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.