# Slack Notifier MCP Server

An MCP server that connects to Slack via Socket Mode (WebSocket) and surfaces real-time message notifications through MCP tools. No public URL or ngrok needed.

## How It Works

This server runs two things simultaneously in a single process:

1. **Slack Socket Mode client** — connects outbound to Slack over WebSocket and receives events in real time
2. **MCP server** (stdio) — exposes tools to query, filter, and manage those notifications

When someone posts a message in Slack, the Socket Mode connection pushes the event to your server. The server stores it in memory (with optional disk persistence), and you can query it via the MCP tools.

## Setup

### 1. Create a Slack App

1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** → **From scratch**
2. Name it something like "Message Notifier" and pick your workspace

### 2. Enable Socket Mode

1. Go to **Settings** → **Socket Mode** and toggle it **On**
2. You'll be prompted to create an **App-Level Token** — name it something like "socket-mode-token"
3. Give it the **`connections:write`** scope
4. Copy the token (starts with `xapp-`) — this is your `SLACK_APP_TOKEN`

### 3. Subscribe to Events

1. Go to **Features** → **Event Subscriptions** and toggle it **On**
2. Under **Subscribe to bot events**, add:
   - `message.channels` — messages in public channels
   - `message.groups` — messages in private channels
   - `message.im` — direct messages
   - `message.mpim` — group direct messages
3. Save changes

### 4. Add Bot Token Scopes

1. Go to **Features** → **OAuth & Permissions**
2. Under **Bot Token Scopes**, add:
   - `channels:history` — read messages in public channels
   - `groups:history` — read messages in private channels
   - `im:history` — read direct messages
   - `mpim:history` — read group DMs
3. Install (or reinstall) the app to your workspace

### 5. Invite the Bot

Invite your bot to the channels you want to monitor:
```
/invite @Message Notifier
```

### 6. Configure the MCP Server

Add this to your Claude Desktop / Claude Code MCP config:

```json
{
  "mcpServers": {
    "slack-notifier": {
      "command": "node",
      "args": ["/path/to/slack-notifier-mcp-server/dist/index.js"],
      "env": {
        "SLACK_APP_TOKEN": "xapp-1-your-token-here",
        "PERSIST_PATH": "/path/to/notifications.json"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SLACK_APP_TOKEN` | **Yes** | — | App-level token (`xapp-...`) with `connections:write` scope |
| `PERSIST_PATH` | No | — | File path to persist notifications across restarts |

## Available MCP Tools

### `slack_get_notifications`
Retrieve stored message notifications with filtering:
- Filter by channel, read status, time range
- Pagination support
- Returns newest messages first

### `slack_mark_notifications_read`
Mark notifications as read:
- By specific IDs
- All at once (optionally per-channel)

### `slack_notification_stats`
Get a summary of notification counts grouped by channel — total and unread per channel.

### `slack_clear_notifications`
Permanently delete all stored notifications (requires confirmation).

## Building

```bash
npm install
npm run build
```

## Running

```bash
SLACK_APP_TOKEN=xapp-1-... npm start
```

The server will connect to Slack via Socket Mode and start the MCP stdio server simultaneously.