signal-mcp-server

stefanstranger/signal-mcp-server

3.3

If you are the rightful owner of signal-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Signal MCP Server allows AI agents and tools to access Signal Desktop chat messages and attachments through the Model Context Protocol (MCP).

📱 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

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

2. Python

3. UV (Python Package Manager)

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

🙏 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.