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

{
  "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

uv run .\server.py

Inspect MCP Server

Using the MCP Inspector:

npx @modelcontextprotocol/inspector uv run --with mcp[cli] mcp run c://github//signal-mcp-server//server.py

Using mcptools:

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:

[
  {
    "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:

[
  {
    "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:

[
  {
    "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
• 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.