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/
• 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.