mcp-signal

Локальный сервер протокола контекста модели (MCP), который считывает историю Signal Desktop из локальной зашифрованной базы данных через signal-export и отправляет исходящие сообщения через signal-cli.

mcp-signal фокусируется на основном рабочем процессе для личной автоматизации Signal — список чатов, чтение сообщений, поиск по сообщениям, просмотр групп и отправка сообщений в личные или групповые чаты. Все работает локально; используется транспорт stdio без сетевого прослушивателя.

Внимание — смешанный бэкенд. Чтение/поиск осуществляется из локальной базы данных Signal Desktop. Для отправки используется signal-cli, который должен быть установлен и привязан к учетной записи Signal отдельно. Если signal-cli недоступен, чтение/поиск будут работать, но инструменты отправки — нет.

Функции

• Список личных и групповых чатов из Signal Desktop

• Чтение последних сообщений из чата

• Поиск сообщений в одном чате или по всем чатам

• Список групповых чатов с идентификаторами групп signal-cli для исходящих сообщений

• Отправка сообщения:

  • прямому получателю по номеру телефона

  • в группу по идентификатору группы

  • в чат по точному названию чата (с проверкой неоднозначности)

• Работает полностью на вашем компьютере; транспорт stdio без сетевого прослушивателя

Настройка

Предварительные требования

• Python 3.13+

• uv

• Signal Desktop с существующей локальной базой данных сообщений

• signal-cli, установленный и привязанный, если вы хотите отправлять сообщения

Установка

1. Клонируйте этот репозиторий

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

2. Установите зависимости

   uv sync

3. Установите signal-cli (необязательно — нужно только для исходящих сообщений)

   В macOS проще всего использовать Homebrew:

   brew install signal-cli

Настройка исходящих сообщений

Сервер автоматически загружает локальный файл .env.local из корня репозитория, если он существует. Этот файл игнорируется git и является рекомендуемым местом для локальной конфигурации машины.

cat > .env.local <<'EOF'
SIGNAL_ACCOUNT="+441234567890"
EOF

Необязательные переменные окружения:

Переменные окружения, установленные в оболочке, имеют приоритет над .env.local.

Привязка signal-cli (только при первом запуске)

mcp-signal не управляет привязкой самостоятельно. Сначала привяжите локальное устройство signal-cli:

signal-cli link -n "signal-mcp"

Отсканируйте QR-код в мобильном приложении Signal (Настройки → Связанные устройства → Связать новое устройство).

Не передавайте -a / --account в команду link в текущих версиях signal-cli — привязка нового вторичного устройства не требует номера телефона.

После того как QR-код будет принят, убедитесь, что связанная учетная запись видна:

signal-cli listAccounts

Эта учетная запись должна соответствовать значению SIGNAL_ACCOUNT в .env.local.

signal-cli хранит состояние связанной учетной записи в своей собственной локальной директории данных (обычно ~/.local/share/signal-cli/data в macOS/Linux). Это состояние находится вне этого репозитория и не коммитится в mcp-signal.

Проверьте, что все подключено:

uv run signal-mcp smoke

Конфигурация MCP-клиента

Все клиенты запускают сервер одинаково через stdio. В macOS вам может потребоваться абсолютный путь к uv — см. macOS: uv PATH ниже.

Claude Code

Самый быстрый путь — через CLI:

claude mcp add --transport stdio signal --scope user -- uv run --directory /absolute/path/to/mcp-signal signal-mcp serve

Альтернативно, добавьте в .mcp.json в корне вашего проекта (или ~/.claude.json для сервера на уровне пользователя):

{
  "mcpServers": {
    "signal": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Если вы редактируете файл напрямую, перезапустите сессию Claude Code, чтобы изменения вступили в силу.

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Перезапустите Claude Desktop. Вы должны увидеть signal в списке доступных интеграций.

Cursor

Добавьте в ~/.cursor/mcp.json:

{
  "mcpServers": {
    "signal": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Перезапустите Cursor.

macOS: uv PATH

Графические приложения (Claude Desktop, Cursor) не всегда наследуют PATH из вашего интерактивного терминала, поэтому uv может выдать ошибку spawn uv ENOENT. Исправьте это, используя абсолютный путь к uv в command:

• Homebrew — /opt/homebrew/bin/uv (Apple Silicon) или /usr/local/bin/uv (Intel)

• Ручная установка — выполните which uv в терминале, чтобы найти путь

Пример:

{
  "mcpServers": {
    "signal": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-signal", "signal-mcp", "serve"]
    }
  }
}

Архитектура

Поток данных

1. MCP-клиент запускает signal-mcp serve через stdio.

2. Инструменты чтения/поиска вызывают signal-export для локальной базы данных Signal Desktop.

3. Список групп и исходящие сообщения вызывают signal-cli -a ACCOUNT jsonRpc.

4. Результаты возвращаются в виде структурированного JSON.

Структура проекта

mcp-signal/
  src/mcp_signal/
    config.py
    main.py
    reader.py
    server.py
    signal_cli.py
  tests/
  CLAUDE.md
  LICENSE
  README.md
  SECURITY.md

Инструменты

Конфиденциальность и безопасность

• Нет облачного ретранслятора. Нет сетевого прослушивателя. Все данные остаются на вашем компьютере.

• Чтение/поиск использует только ваши локальные данные Signal Desktop.

• Операции отправки требуют локально настроенной учетной записи signal-cli.

• .env.local предназначен для локальных секретов, таких как SIGNAL_ACCOUNT, и не коммитится.

• Состояние связанного устройства signal-cli хранится в его собственной локальной директории данных приложения, вне этого репозитория, и не коммитится.

См. SECURITY.md для получения информации о том, как сообщать об уязвимостях.

Ограничения

• Риск инъекции промптов: как и многие MCP-серверы, этот подвержен смертельному трио. Вредоносные входящие сообщения могут попытаться дать агенту команду на эксфильтрацию других сообщений. Относитесь к поверхности инструментов соответствующим образом и проверяйте исходящие действия перед их одобрением.

• Смешанный бэкенд: история чатов берется из Signal Desktop, а исходящие сообщения — из signal-cli.

• Нет вложений: отправка только текста.

• Нет уведомлений в реальном времени: только опрос/чтение.

• Одна учетная запись на экземпляр MCP.

• Для отправки в группы нужен signal-cli: одного чтения локальной БД недостаточно для безопасной отправки в группы.

Разработка

uv sync
uv run signal-mcp smoke
uv run pytest
uv run ruff check .

Устранение неполадок

• signal-cli не найден — убедитесь, что signal-cli находится в PATH, или установите SIGNAL_CLI_PATH в .env.local. В macOS проще всего использовать brew install signal-cli.

• Чтение/поиск работают, но отправка не удается — signal-cli не привязан или не установлен SIGNAL_ACCOUNT. Выполните signal-cli listAccounts для проверки, затем проверьте .env.local.

• signal-cli link зависает или выдает ошибку — не передавайте -a / --account в link в текущих версиях. Выполните signal-cli link -n "signal-mcp" и отсканируйте QR-код с телефона.

• MCP-клиент не может запустить сервер — args должны содержать абсолютный путь к репозиторию, а не относительный. Если сам uv выдает ошибку spawn uv ENOENT, см. macOS: uv PATH.

• Сообщения не возвращаются — убедитесь, что Signal Desktop установлен и имеет историю сообщений. Путь чтения запрашивает локальную базу данных Signal Desktop напрямую.

Участие в разработке

Приветствуются вклады через pull request. Пожалуйста:

• Выполните uv run ruff check . перед отправкой.

• Убедитесь, что uv run pytest проходит успешно.

См. CLAUDE.md для полного рабочего процесса разработки.

Лицензия

Лицензия MIT — см. LICENSE.