sgnl-mcp — MCP-сервер для SIGNAL

Подключает SIGNAL к ИИ-ассистенту: Claude Desktop, Claude Code, Codex и другим клиентам с поддержкой MCP. Ассистенту можно писать обычным языком: «покажи проекты», «найди в проекте Школа документы АР в PDF», «какие замечания по этому документу ещё открыты».

Что ассистент может делать, зависит от профиля:

Удалять, перемещать и переименовывать документы и папки, а также менять права доступа ассистент не может ни в одном профиле.

Содержание

• Что понадобится
• Способ 1. Через uvx
• Способ 2. Через Docker
• Проверка
• Профили write и workflow
• Обновление
• Если что-то не работает
• Для администратора SIGNAL
• Все настройки
• Что умеет ассистент

Что понадобится

1. Ключ SIGNAL: client_id и client_secret интеграции. Их выдаёт администратор SIGNAL вашей компании; что ему нужно сделать, описано в разделе Для администратора SIGNAL. Scope и другие технические детали вам знать не нужно.
2. Клиент с поддержкой MCP: Claude Desktop, Claude Code или Codex (CLI, расширение для IDE или десктопное приложение). ChatGPT в браузере и облачный Codex к этому серверу не подключаются: им нужен сервер в интернете, а этот работает на вашем компьютере.
3. Один из двух способов запуска:

Оба способа запускают один и тот же сервер, и работает он одинаково. Можно установить оба и переключаться между ними.

Ниже 0.2.1 — текущая версия. Номер последней версии можно посмотреть на PyPI.

Способ 1. Через uvx

Шаг 1. Установите uv

Windows, в PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS и Linux, в терминале:

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

Закройте терминал, откройте его снова и узнайте полный путь к uvx. Он понадобится в настройках клиента.

where.exe uvx      # Windows, обычно C:\Users\<имя>\.local\bin\uvx.exe

which uvx          # macOS и Linux, обычно /Users/<имя>/.local/bin/uvx

Python отдельно ставить не нужно: если его нет, uv скачает его сам.

Шаг 2. Проверьте ключ

Windows (PowerShell):

$env:SGNL_CLIENT_ID="ваш client_id"
$env:SGNL_CLIENT_SECRET="ваш client_secret"
uvx sgnl-mcp@0.2.1

macOS и Linux:

SGNL_CLIENT_ID="ваш client_id" SGNL_CLIENT_SECRET="ваш client_secret" uvx sgnl-mcp@0.2.1

Первый запуск длится 10–20 секунд: скачиваются пакеты. Возможны три результата:

• Курсор мигает, сообщений нет. Всё в порядке: сервер подключился к SIGNAL и ждёт клиента. Остановите его через Ctrl+C.
• started with limited rights. Сервер работает, но части операций ключу не хватает прав. В сообщении указано, что передать администратору. Пользоваться можно и так.
• cannot start или invalid configuration. Ключ неверный или не задан, см. раздел Если что-то не работает.

Шаг 3. Подключите к клиенту

Claude Desktop. Откройте файл настроек:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Добавьте в него блок sgnl. Если в файле уже есть "mcpServers", добавьте только сам блок "sgnl": {…} рядом с остальными серверами.

{
  "mcpServers": {
    "sgnl": {
      "command": "C:\\Users\\Admin\\.local\\bin\\uvx.exe",
      "args": ["sgnl-mcp@0.2.1"],
      "env": {
        "SGNL_CLIENT_ID": "ваш client_id",
        "SGNL_CLIENT_SECRET": "ваш client_secret",
        "SGNL_MCP_PROFILE": "read"
      }
    }
  }
}

В command укажите путь из шага 1. В Windows обратные слеши удваиваются (\\), на macOS путь пишется как есть: /Users/me/.local/bin/uvx. Затем полностью закройте Claude Desktop (на Windows через значок в трее → Quit) и запустите снова.

Claude Code:

claude mcp add sgnl -e SGNL_CLIENT_ID=ваш_client_id -e SGNL_CLIENT_SECRET=ваш_client_secret -- uvx sgnl-mcp@0.2.1

Codex. Файл ~/.codex/config.toml, на Windows это %USERPROFILE%\.codex\config.toml:

[mcp_servers.sgnl]
command = "uvx"
args = ["sgnl-mcp@0.2.1"]
env = { SGNL_CLIENT_ID = "ваш client_id", SGNL_CLIENT_SECRET = "ваш client_secret" }
startup_timeout_sec = 30

Журнал действий ассистента хранится в папке .sgnl-mcp в домашнем каталоге, файл audit.jsonl.

Способ 2. Через Docker

Шаг 1. Установите Docker Desktop и скачайте образ

Скачайте Docker Desktop с docker.com, установите и запустите. Затем выполните:

docker pull ghcr.io/gritsyuk/sgnl-mcp:0.2.1

Образ подходит для Windows, Linux и Mac с процессорами Intel и Apple.

Шаг 2. Сохраните ключ в файл

Создайте текстовый файл, например C:\Users\Admin\sgnl-mcp.env (Windows) или ~/sgnl-mcp.env (macOS, Linux):

SGNL_CLIENT_ID=ваш client_id
SGNL_CLIENT_SECRET=ваш client_secret
SGNL_MCP_PROFILE=read

Кавычки и пробелы вокруг = не нужны.

Шаг 3. Проверьте ключ

Windows (cmd или PowerShell):

docker run -i --rm --init --env-file C:\Users\Admin\sgnl-mcp.env ghcr.io/gritsyuk/sgnl-mcp:0.2.1

macOS и Linux:

docker run -i --rm --init --env-file ~/sgnl-mcp.env ghcr.io/gritsyuk/sgnl-mcp:0.2.1

Результаты те же, что для uvx: если курсор мигает без сообщений, всё в порядке. Остановите сервер через Ctrl+C.

Шаг 4. Подключите к клиенту

Claude Desktop (где лежит файл настроек, см. способ 1):

{
  "mcpServers": {
    "sgnl": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--read-only", "--tmpfs", "/tmp",
        "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
        "--env-file", "C:\\Users\\Admin\\sgnl-mcp.env",
        "-v", "sgnl-mcp-data:/data",
        "ghcr.io/gritsyuk/sgnl-mcp:0.2.1"
      ]
    }
  }
}

На macOS и Linux в --env-file укажите полный путь без ~, например /Users/me/sgnl-mcp.env. После изменения полностью перезапустите Claude Desktop.

Claude Code:

claude mcp add sgnl -- docker run -i --rm --init --read-only --tmpfs /tmp --cap-drop ALL \
  --security-opt no-new-privileges --env-file ~/sgnl-mcp.env -v sgnl-mcp-data:/data \
  ghcr.io/gritsyuk/sgnl-mcp:0.2.1

Codex (~/.codex/config.toml):

[mcp_servers.sgnl]
command = "docker"
args = [
  "run", "-i", "--rm", "--init", "--read-only", "--tmpfs", "/tmp",
  "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
  "--env-file", "C:\\Users\\Admin\\sgnl-mcp.env",
  "-v", "sgnl-mcp-data:/data",
  "ghcr.io/gritsyuk/sgnl-mcp:0.2.1",
]
startup_timeout_sec = 30

Что значат параметры запуска:

Журнал действий хранится в томе Docker sgnl-mcp-data, файл audit.jsonl.

Проверка

Напишите ассистенту: «Подключён ли SIGNAL? Покажи список проектов».

• Ассистент вызовет get_access_status и list_projects и покажет проекты, доступные вашему ключу.
• Если ключу чего-то не хватает, ассистент скажет об этом и приведёт готовый текст для администратора.

Claude Desktop запускает сервер дважды: для обычного чата и для режимов Cowork и Code. Поэтому в Docker Desktop видно два контейнера, а в Диспетчере задач два процесса. Это нормально.

Профили write и workflow

Для изменений в SIGNAL нужны ещё три настройки. Для uvx они добавляются в env, для Docker в env-файл.

SGNL_MCP_PROFILE=write
SGNL_MCP_ACTOR_USER_ID=<ID пользователя SIGNAL, от имени которого вносятся изменения>
SGNL_MCP_UPLOAD_ROOT=<папка с файлами, которые ассистенту можно загружать>

• SGNL_MCP_ACTOR_USER_ID: ID пользователя SIGNAL. Обычно это служебная учётная запись, например «AI-агент»; её ID даёт администратор SIGNAL.
• SGNL_MCP_UPLOAD_ROOT: файлы вне этой папки ассистент загрузить не может.
• Docker: SGNL_MCP_UPLOAD_ROOT не задавайте, а подключите папку параметром перед именем образа, только для чтения:

  "-v", "C:\\SIGNAL\\outgoing:/uploads:ro",
  

Как проходит изменение:

1. Ассистент показывает, что именно изменится: «было → станет», путь папки, состав передачи.
2. Изменение выполняется только после вашего согласия в чате.
3. Отправку передачи и запуск рассмотрения (профиль workflow) вы дополнительно подтверждаете в отдельном диалоге клиента.

В настройках клиента не включайте «разрешить всегда» для инструментов записи: пусть клиент спрашивает перед каждым изменением.

Обновление

Замените номер версии в настройках клиента, например 0.2.1 → 0.3.0, и перезапустите клиент.

• uvx: новая версия скачается сама при первом запуске.
• Docker: сначала скачайте образ: docker pull ghcr.io/gritsyuk/sgnl-mcp:0.3.0.

Указывайте конкретную версию, а не latest: тогда сервер не обновится без вашего ведома.

Если что-то не работает

Журнал запуска сервера в Claude Desktop:

• Windows: %APPDATA%\Claude\logs\mcp-server-sgnl.log
• macOS: ~/Library/Logs/Claude/mcp-server-sgnl.log

Если ассистент отвечает, что ключу не хватает прав (SCOPE_MISSING), перешлите его сообщение администратору SIGNAL: в нём уже указано, какие права нужно добавить. После этого перезапустите клиент.

Для администратора SIGNAL

Чтобы выдать сотруднику ключ, создайте интеграцию в SIGNAL («Редактировать интеграцию»):

1. Название: например, MCP_READ или MCP_<сотрудник>.
2. scopes: отметьте права профиля из таблицы ниже.
3. Проект: только проекты, с которыми сотрудник должен работать через ассистента.
4. Действительно до: для ключей с правами на запись лучше ставить короткий срок.

Передайте сотруднику client_id и client_secret. «Обновить ключ доступа» выпускает новый client_secret, старый перестаёт работать.

Обратите внимание на похожие названия: нужен docs:issue:list, а не docs:issue:read.

Если каких-то прав из списка нет, сервер всё равно работает, но соответствующие операции недоступны. Сотрудник получит сообщение с перечнем недостающих прав. Права на удаление (*:delete), управление доступом (docs:permissions:*) и пользователями сервер не использует: выдавать их не нужно.

Для профилей write и workflow заведите служебного пользователя (например, «AI-агент») и сообщите сотруднику его ID. От его имени будут вноситься изменения.

Все настройки

Что умеет ассистент

Чего ассистент не делает: не создаёт замечания; не удаляет, не перемещает и не переименовывает документы и папки; не меняет права и пользователей. Найти передачи по конкретному документу нельзя: такой возможности нет в API SIGNAL.

Нагрузка на SIGNAL ограничена: по умолчанию не больше 3 запросов в секунду, справочники запоминаются на 5 минут.