@jtalk22/slack-mcp 3.1.0 → 3.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -426
- package/docs/API.md +134 -0
- package/docs/SETUP.md +64 -29
- package/docs/TROUBLESHOOTING.md +28 -0
- package/lib/handlers.js +156 -0
- package/lib/slack-client.js +11 -3
- package/lib/token-store.js +6 -5
- package/lib/tools.js +132 -1
- package/package.json +15 -8
- package/public/index.html +10 -6
- package/public/share.html +6 -5
- package/scripts/setup-wizard.js +2 -2
- package/server.json +8 -2
- package/src/server-http.js +16 -1
- package/src/server.js +31 -7
- package/src/web-server.js +117 -4
- package/docs/CLOUDFLARE-BROWSER-TOOLKIT.md +0 -67
- package/docs/COMMUNICATION-STYLE.md +0 -66
- package/docs/COMPATIBILITY.md +0 -19
- package/docs/DEPLOYMENT-MODES.md +0 -55
- package/docs/HN-LAUNCH.md +0 -72
- package/docs/INDEX.md +0 -41
- package/docs/INSTALL-PROOF.md +0 -18
- package/docs/LAUNCH-COPY-v3.0.0.md +0 -101
- package/docs/LAUNCH-MATRIX.md +0 -22
- package/docs/LAUNCH-OPS.md +0 -71
- package/docs/RELEASE-HEALTH.md +0 -77
- package/docs/SUPPORT-BOUNDARIES.md +0 -49
- package/docs/USE_CASE_RECIPES.md +0 -69
- package/docs/WEB-API.md +0 -303
- package/docs/images/demo-channel-messages.png +0 -0
- package/docs/images/demo-channels.png +0 -0
- package/docs/images/demo-claude-mobile-360x800.png +0 -0
- package/docs/images/demo-claude-mobile-390x844.png +0 -0
- package/docs/images/demo-claude-mobile-poster.png +0 -0
- package/docs/images/demo-main-mobile-360x800.png +0 -0
- package/docs/images/demo-main-mobile-390x844.png +0 -0
- package/docs/images/demo-main.png +0 -0
- package/docs/images/demo-messages.png +0 -0
- package/docs/images/demo-poster.png +0 -0
- package/docs/images/demo-sidebar.png +0 -0
- package/docs/images/diagram-oauth-comparison.svg +0 -80
- package/docs/images/diagram-session-flow.svg +0 -105
- package/docs/images/social-preview-v3.png +0 -0
- package/docs/images/web-api-mobile-360x800.png +0 -0
- package/docs/images/web-api-mobile-390x844.png +0 -0
- package/public/demo-claude.html +0 -1974
- package/public/demo-video.html +0 -244
- package/public/demo.html +0 -1196
- package/scripts/build-mobile-demo.js +0 -168
- package/scripts/build-release-health-delta.js +0 -201
- package/scripts/build-social-preview.js +0 -189
- package/scripts/capture-screenshots.js +0 -152
- package/scripts/check-owner-attribution.sh +0 -131
- package/scripts/check-public-language.sh +0 -26
- package/scripts/check-version-parity.js +0 -218
- package/scripts/cloudflare-browser-tool.js +0 -237
- package/scripts/collect-release-health.js +0 -162
- package/scripts/impact-push-v3.js +0 -781
- package/scripts/record-demo.js +0 -163
- package/scripts/release-preflight.js +0 -247
- package/scripts/setup-git-hooks.sh +0 -15
- package/scripts/update-github-social-preview.js +0 -208
- package/scripts/verify-core.js +0 -159
- package/scripts/verify-install-flow.js +0 -193
- package/scripts/verify-web.js +0 -273
package/README.md
CHANGED
|
@@ -1,239 +1,60 @@
|
|
|
1
1
|
# Slack MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@jtalk22/slack-mcp)
|
|
4
|
+
[](https://www.npmjs.com/package/@jtalk22/slack-mcp)
|
|
5
|
+
[](https://registry.modelcontextprotocol.io)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
Give Claude your Slack. 16 tools — read channels, search messages, send replies, react, manage unreads. Self-host free or Cloud from $19/mo.
|
|
9
|
+
|
|
10
|
+
## Tools
|
|
11
|
+
|
|
12
|
+
| Tool | Description | Safety |
|
|
13
|
+
|------|-------------|--------|
|
|
14
|
+
| `slack_health_check` | Verify token validity and workspace info | read-only |
|
|
15
|
+
| `slack_token_status` | Token age, health, and cache stats | read-only |
|
|
16
|
+
| `slack_refresh_tokens` | Auto-extract fresh tokens from Chrome | read-only* |
|
|
17
|
+
| `slack_list_conversations` | List DMs and channels | read-only |
|
|
18
|
+
| `slack_conversations_history` | Get messages from a channel or DM | read-only |
|
|
19
|
+
| `slack_get_full_conversation` | Export full history with threads | read-only |
|
|
20
|
+
| `slack_search_messages` | Search across workspace | read-only |
|
|
21
|
+
| `slack_get_thread` | Get thread replies | read-only |
|
|
22
|
+
| `slack_users_info` | Get user details | read-only |
|
|
23
|
+
| `slack_list_users` | List workspace users (paginated, 500+) | read-only |
|
|
24
|
+
| `slack_users_search` | Search users by name, display name, or email | read-only |
|
|
25
|
+
| `slack_conversations_unreads` | Get channels/DMs with unread messages | read-only |
|
|
26
|
+
| `slack_send_message` | Send a message to any conversation | **destructive** |
|
|
27
|
+
| `slack_add_reaction` | Add an emoji reaction to a message | **destructive** |
|
|
28
|
+
| `slack_remove_reaction` | Remove an emoji reaction from a message | **destructive** |
|
|
29
|
+
| `slack_conversations_mark` | Mark a conversation as read | **destructive** |
|
|
30
|
+
|
|
31
|
+
All tools carry [MCP safety annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations): 12 read-only (`readOnlyHint: true`), 4 write-path (`destructiveHint: true`). Only `slack_send_message` is non-idempotent.
|
|
32
|
+
|
|
33
|
+
\* `slack_refresh_tokens` modifies local token file only — no external Slack state.
|
|
34
|
+
|
|
35
|
+
## Cloud (Recommended)
|
|
36
|
+
|
|
37
|
+
Skip all local setup. Paste one URL into Claude and get 16 Slack tools in 60 seconds. Encrypted token storage on Cloudflare's edge (300+ PoPs). OAuth 2.1 with PKCE S256.
|
|
37
38
|
|
|
38
39
|
| Plan | Price | Includes |
|
|
39
40
|
|------|-------|----------|
|
|
40
|
-
| Solo | $19/mo |
|
|
41
|
-
| Team | $49/mo |
|
|
42
|
-
|
|
43
|
-
[Get started](https://jtalk22.github.io/slack-mcp-server/cloud.html) — no Docker, no tokens, no admin approval.
|
|
44
|
-
|
|
45
|
-
## 60-Second Hosted Migration
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
export SLACK_TOKEN=xoxc-...
|
|
49
|
-
export SLACK_COOKIE=xoxd-...
|
|
50
|
-
export SLACK_MCP_HTTP_AUTH_TOKEN=change-this
|
|
51
|
-
export SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai
|
|
52
|
-
node src/server-http.js
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
Request with:
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
Authorization: Bearer <SLACK_MCP_HTTP_AUTH_TOKEN>
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
Emergency local fallback only:
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
SLACK_MCP_HTTP_INSECURE=1 node src/server-http.js
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
For guided hosted rollout requirements, open: [deployment intake](https://github.com/jtalk22/slack-mcp-server/issues/new?template=deployment-intake.md)
|
|
68
|
-
|
|
69
|
-
### Why This Exists
|
|
70
|
-
|
|
71
|
-
I built this because I was working with someone to help me manage a complex workload, and we kept hitting walls. They needed context from my messages—"what did X say about Y?"—and standard app/OAuth flows were too constrained for that workflow.
|
|
72
|
-
|
|
73
|
-
Screenshotting messages is not a workflow.
|
|
74
|
-
|
|
75
|
-
This server bridges the gap. It creates a secure, local bridge between Claude and your Slack web session. It gives your MCP client the same access **you** already have in the browser—search history, summarize threads, and retrieve prior context—without fighting the platform.
|
|
76
|
-
|
|
77
|
-

|
|
78
|
-
|
|
79
|
-
---
|
|
80
|
-
|
|
81
|
-
## Architecture: Local Session Mirroring
|
|
82
|
-
|
|
83
|
-
Instead of authenticating as a bot, this server leverages your existing Chrome session credentials (macOS) or manual token injection (Linux/Windows). It mirrors your user access exactly—if you can see it in Slack, Claude can see it too.
|
|
84
|
-
|
|
85
|
-

|
|
86
|
-
|
|
87
|
-
### Why Not OAuth?
|
|
88
|
-
|
|
89
|
-

|
|
41
|
+
| Solo | $19/mo | 16 standard tools, AES-256-GCM encrypted storage, 5K requests/mo |
|
|
42
|
+
| Team | $49/mo | 16 standard + 3 AI compound tools, 3 workspaces, 25K requests/mo |
|
|
90
43
|
|
|
91
|
-
|
|
44
|
+
[Get Started](https://jtalk22.github.io/slack-mcp-server/cloud.html) · [Privacy Policy](https://jtalk22.github.io/slack-mcp-server/privacy.html)
|
|
92
45
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
## Features
|
|
96
|
-
|
|
97
|
-
### Core Capabilities
|
|
98
|
-
- **Read Any Message** - DMs, private channels, public channels
|
|
99
|
-
- **Full Export** - Conversations with threads and resolved usernames
|
|
100
|
-
- **Search** - Query across your entire workspace
|
|
101
|
-
- **Send Messages** - DMs or channels, with thread support
|
|
102
|
-
- **User Directory** - List and search 500+ users with pagination
|
|
103
|
-
|
|
104
|
-
### Stability
|
|
105
|
-
- **Auto Token Refresh** - Extracts fresh tokens from Chrome automatically *(macOS only)*
|
|
106
|
-
- **Atomic Writes** - File operations use temp-file-then-rename to prevent corruption
|
|
107
|
-
- **Zombie Protection** - Background timers use `unref()` for clean process exit
|
|
108
|
-
- **Race Condition Safety** - Mutex locks prevent concurrent token extraction
|
|
109
|
-
- **Rate Limit Handling** - Exponential backoff with jitter
|
|
110
|
-
|
|
111
|
-
### Tools
|
|
112
|
-
| Tool | Description |
|
|
113
|
-
|------|-------------|
|
|
114
|
-
| `slack_health_check` | Verify token validity and workspace info |
|
|
115
|
-
| `slack_token_status` | Detailed token age, health, and cache stats |
|
|
116
|
-
| `slack_refresh_tokens` | Auto-extract fresh tokens from Chrome |
|
|
117
|
-
| `slack_list_conversations` | List DMs/channels (with lazy discovery cache) |
|
|
118
|
-
| `slack_conversations_history` | Get messages from a channel or DM |
|
|
119
|
-
| `slack_get_full_conversation` | Export full history with threads |
|
|
120
|
-
| `slack_search_messages` | Search across workspace |
|
|
121
|
-
| `slack_send_message` | Send a message to any conversation |
|
|
122
|
-
| `slack_get_thread` | Get thread replies |
|
|
123
|
-
| `slack_users_info` | Get user details |
|
|
124
|
-
| `slack_list_users` | List workspace users (paginated, 500+ supported) |
|
|
125
|
-
|
|
126
|
-
---
|
|
127
|
-
|
|
128
|
-
## Quick Start
|
|
46
|
+
## Install (Self-Hosted)
|
|
129
47
|
|
|
130
48
|
**Runtime:** Node.js 20+
|
|
131
49
|
|
|
132
|
-
### 30-Second Compatibility Check
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
npx -y @jtalk22/slack-mcp --setup
|
|
136
|
-
npx -y @jtalk22/slack-mcp --doctor
|
|
137
|
-
npx -y @jtalk22/slack-mcp --status
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Expected:
|
|
141
|
-
- `--setup` launches the interactive wizard
|
|
142
|
-
- `--doctor` returns one clear next action with exit code:
|
|
143
|
-
- `0` ready
|
|
144
|
-
- `1` missing credentials
|
|
145
|
-
- `2` invalid/expired credentials
|
|
146
|
-
- `3` connectivity/runtime issue
|
|
147
|
-
- `--status` is read-only and non-mutating
|
|
148
|
-
|
|
149
|
-
Command reference: [HN launch kit](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/HN-LAUNCH.md)
|
|
150
|
-
|
|
151
|
-
### Known Working Clients
|
|
152
|
-
|
|
153
|
-
- Claude Desktop (macOS/Windows/Linux)
|
|
154
|
-
- Claude Code CLI
|
|
155
|
-
- Local browser mode (`web`)
|
|
156
|
-
- Hosted Node runtime (`http`)
|
|
157
|
-
- Cloudflare Worker / Smithery transport
|
|
158
|
-
|
|
159
|
-
Compatibility matrix: [compatibility matrix](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/COMPATIBILITY.md)
|
|
160
|
-
|
|
161
|
-
### Option A: npm (Recommended)
|
|
162
|
-
|
|
163
|
-
```bash
|
|
164
|
-
npm install -g @jtalk22/slack-mcp
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
### Option B: Clone Repository
|
|
168
|
-
|
|
169
|
-
```bash
|
|
170
|
-
git clone https://github.com/jtalk22/slack-mcp-server.git
|
|
171
|
-
cd slack-mcp-server
|
|
172
|
-
npm install
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
### Option C: Docker
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
docker pull ghcr.io/jtalk22/slack-mcp-server:latest
|
|
179
|
-
```
|
|
180
|
-
|
|
181
|
-
### Install Sanity (Clean Temp Directory)
|
|
182
|
-
|
|
183
|
-
```bash
|
|
184
|
-
tmpdir="$(mktemp -d)"
|
|
185
|
-
cd "$tmpdir"
|
|
186
|
-
npx -y @jtalk22/slack-mcp --version
|
|
187
|
-
npx -y @jtalk22/slack-mcp --help
|
|
188
|
-
npx -y @jtalk22/slack-mcp --status
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
Expected:
|
|
192
|
-
- `--version` and `--help` exit `0`
|
|
193
|
-
- `--status` exits non-zero until credentials are configured
|
|
194
|
-
- `--status` is read-only and never attempts Chrome extraction
|
|
195
|
-
|
|
196
|
-
---
|
|
197
|
-
|
|
198
|
-
## Configuration
|
|
199
|
-
|
|
200
|
-
### Step 1: Get Your Tokens
|
|
201
|
-
|
|
202
|
-
#### Setup Wizard (Recommended)
|
|
203
|
-
|
|
204
|
-
The interactive setup wizard handles token extraction and validation automatically:
|
|
205
|
-
|
|
206
50
|
```bash
|
|
207
51
|
npx -y @jtalk22/slack-mcp --setup
|
|
208
52
|
```
|
|
209
53
|
|
|
210
|
-
|
|
211
|
-
- **Linux/Windows**: Guides you through manual extraction step-by-step
|
|
212
|
-
- Validates tokens against Slack API before saving
|
|
213
|
-
- Stores tokens securely at `~/.slack-mcp-tokens.json`
|
|
214
|
-
|
|
215
|
-
#### Check Token Status
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
npx -y @jtalk22/slack-mcp --status
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
#### Alternative: Manual Token Scripts
|
|
222
|
-
|
|
223
|
-
```bash
|
|
224
|
-
# macOS auto-extraction
|
|
225
|
-
npm run tokens:auto
|
|
54
|
+
The setup wizard handles token extraction and validation automatically.
|
|
226
55
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
# Check health
|
|
231
|
-
npm run tokens:status
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
### Step 2: Configure Claude
|
|
235
|
-
|
|
236
|
-
#### Claude Desktop (macOS)
|
|
56
|
+
<details>
|
|
57
|
+
<summary><strong>Claude Desktop (macOS)</strong></summary>
|
|
237
58
|
|
|
238
59
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
239
60
|
|
|
@@ -248,7 +69,10 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
|
248
69
|
}
|
|
249
70
|
```
|
|
250
71
|
|
|
251
|
-
|
|
72
|
+
</details>
|
|
73
|
+
|
|
74
|
+
<details>
|
|
75
|
+
<summary><strong>Claude Desktop (Windows/Linux)</strong></summary>
|
|
252
76
|
|
|
253
77
|
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
254
78
|
|
|
@@ -267,9 +91,12 @@ Edit `%APPDATA%\Claude\claude_desktop_config.json`:
|
|
|
267
91
|
}
|
|
268
92
|
```
|
|
269
93
|
|
|
270
|
-
>
|
|
94
|
+
> Windows/Linux users must provide tokens via `env` since auto-refresh is macOS-only.
|
|
95
|
+
|
|
96
|
+
</details>
|
|
271
97
|
|
|
272
|
-
|
|
98
|
+
<details>
|
|
99
|
+
<summary><strong>Claude Code CLI</strong></summary>
|
|
273
100
|
|
|
274
101
|
Add to `~/.claude.json`:
|
|
275
102
|
|
|
@@ -285,9 +112,14 @@ Add to `~/.claude.json`:
|
|
|
285
112
|
}
|
|
286
113
|
```
|
|
287
114
|
|
|
288
|
-
|
|
115
|
+
</details>
|
|
289
116
|
|
|
290
|
-
|
|
117
|
+
<details>
|
|
118
|
+
<summary><strong>Docker</strong></summary>
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
docker pull ghcr.io/jtalk22/slack-mcp-server:latest
|
|
122
|
+
```
|
|
291
123
|
|
|
292
124
|
```json
|
|
293
125
|
{
|
|
@@ -302,237 +134,61 @@ Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
|
|
|
302
134
|
}
|
|
303
135
|
```
|
|
304
136
|
|
|
305
|
-
### Step 3: Restart Claude
|
|
306
|
-
|
|
307
|
-
Fully quit and reopen Claude. The Slack tools will appear.
|
|
308
|
-
|
|
309
|
-
---
|
|
310
|
-
|
|
311
|
-
## Architecture
|
|
312
|
-
|
|
313
|
-
### Token Persistence (4 Layers)
|
|
314
|
-
|
|
315
|
-
```
|
|
316
|
-
Priority 1: Environment Variables (SLACK_TOKEN, SLACK_COOKIE)
|
|
317
|
-
↓ fallback
|
|
318
|
-
Priority 2: Token File (~/.slack-mcp-tokens.json)
|
|
319
|
-
↓ fallback
|
|
320
|
-
Priority 3: macOS Keychain (encrypted)
|
|
321
|
-
↓ fallback
|
|
322
|
-
Priority 4: Chrome Auto-Extraction (macOS only)
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
### Stability Features
|
|
326
|
-
|
|
327
|
-
#### Atomic Writes
|
|
328
|
-
All file operations (tokens, DM cache) use atomic writes:
|
|
329
|
-
```
|
|
330
|
-
Write to temp file → chmod 600 → rename to target
|
|
331
|
-
```
|
|
332
|
-
This prevents JSON corruption if the process is killed mid-write.
|
|
333
|
-
|
|
334
|
-
#### Zombie Process Protection
|
|
335
|
-
Background refresh timers use `unref()`:
|
|
336
|
-
```javascript
|
|
337
|
-
const timer = setInterval(refreshTokens, 4 * 60 * 60 * 1000);
|
|
338
|
-
timer.unref(); // Process can exit even if timer is pending
|
|
339
|
-
```
|
|
340
|
-
When Claude closes the MCP connection, the server exits cleanly.
|
|
341
|
-
|
|
342
|
-
#### Race Condition Prevention
|
|
343
|
-
A mutex lock prevents concurrent Chrome extractions:
|
|
344
|
-
```javascript
|
|
345
|
-
if (refreshInProgress) return null; // Skip if already refreshing
|
|
346
|
-
refreshInProgress = true;
|
|
347
|
-
try { return extractFromChromeInternal(); }
|
|
348
|
-
finally { refreshInProgress = false; }
|
|
349
|
-
```
|
|
350
|
-
|
|
351
|
-
---
|
|
352
|
-
|
|
353
|
-
## Web UI (optional browser/local fallback)
|
|
354
|
-
|
|
355
|
-
Claude now supports remote MCP connectors on paid plans. For claude.ai, the preferred path is adding a remote connector in Settings -> Connectors.
|
|
356
|
-
|
|
357
|
-
Reference:
|
|
358
|
-
- https://support.anthropic.com/en/articles/11995447-connectors-in-claude
|
|
359
|
-
- https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp
|
|
360
|
-
|
|
361
|
-
Use this Web UI when you want a local localhost dashboard, REST access, or a fallback workflow without remote connector hosting:
|
|
362
|
-
|
|
363
|
-
```bash
|
|
364
|
-
npm run web
|
|
365
|
-
# Or: npx -y @jtalk22/slack-mcp web
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
**Magic Link:** The console prints a one-click URL with the API key embedded:
|
|
369
|
-
|
|
370
|
-
```
|
|
371
|
-
════════════════════════════════════════════════════════════
|
|
372
|
-
Slack Web API Server v3.0.0
|
|
373
|
-
════════════════════════════════════════════════════════════
|
|
374
|
-
|
|
375
|
-
Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
|
|
376
|
-
```
|
|
377
|
-
|
|
378
|
-
Just click the link - no copy-paste needed. The key is saved to your browser and stripped from the URL for security.
|
|
379
|
-
|
|
380
|
-
<details>
|
|
381
|
-
<summary><strong>Screenshots</strong></summary>
|
|
382
|
-
|
|
383
|
-
| DMs View | Channels View |
|
|
384
|
-
|----------|---------------|
|
|
385
|
-
|  |  |
|
|
386
|
-
|
|
387
137
|
</details>
|
|
388
138
|
|
|
389
|
-
|
|
139
|
+
Restart Claude after configuration. Full setup guide: [docs/SETUP.md](docs/SETUP.md)
|
|
390
140
|
|
|
391
|
-
## Hosted HTTP Mode
|
|
141
|
+
## Hosted HTTP Mode
|
|
392
142
|
|
|
393
|
-
|
|
143
|
+
For remote MCP endpoints (Cloudflare Worker, VPS, etc.):
|
|
394
144
|
|
|
395
145
|
```bash
|
|
396
|
-
SLACK_TOKEN=xoxc-...
|
|
397
|
-
SLACK_COOKIE=xoxd-...
|
|
398
|
-
SLACK_MCP_HTTP_AUTH_TOKEN=change-this
|
|
399
|
-
SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai
|
|
146
|
+
SLACK_TOKEN=xoxc-... \
|
|
147
|
+
SLACK_COOKIE=xoxd-... \
|
|
148
|
+
SLACK_MCP_HTTP_AUTH_TOKEN=change-this \
|
|
149
|
+
SLACK_MCP_HTTP_ALLOWED_ORIGINS=https://claude.ai \
|
|
400
150
|
node src/server-http.js
|
|
401
151
|
```
|
|
402
152
|
|
|
403
|
-
|
|
404
|
-
- `/mcp` requires `Authorization: Bearer <SLACK_MCP_HTTP_AUTH_TOKEN>` by default.
|
|
405
|
-
- Cross-origin browser calls are denied unless origin is listed in `SLACK_MCP_HTTP_ALLOWED_ORIGINS`.
|
|
406
|
-
- For local testing only, you can opt out with `SLACK_MCP_HTTP_INSECURE=1`.
|
|
407
|
-
|
|
408
|
-
---
|
|
409
|
-
|
|
410
|
-
## Operations Guides
|
|
411
|
-
|
|
412
|
-
- [Docs Index](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/INDEX.md) - One-click index for setup, API, troubleshooting, deployment, and support docs
|
|
413
|
-
- [Deployment Modes](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md) - Choose the right operating model (`stdio`, `web`, hosted HTTP, Smithery/Worker)
|
|
414
|
-
- [Use Case Recipes](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/USE_CASE_RECIPES.md) - 12 copy/paste prompts mapped to current tool contracts
|
|
415
|
-
- [Support Boundaries](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SUPPORT-BOUNDARIES.md) - Scope, response targets, and solo-maintainer capacity limits
|
|
416
|
-
- [Release Health](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/RELEASE-HEALTH.md) - Track setup reliability and support-load targets through this release cycle
|
|
417
|
-
|
|
418
|
-
If you're evaluating team rollout, start with [Deployment Modes](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/DEPLOYMENT-MODES.md) before exposing remote endpoints.
|
|
419
|
-
|
|
420
|
-
---
|
|
421
|
-
|
|
422
|
-
## Getting Help Fast
|
|
423
|
-
|
|
424
|
-
1. Run:
|
|
425
|
-
```bash
|
|
426
|
-
npx -y @jtalk22/slack-mcp --version
|
|
427
|
-
npx -y @jtalk22/slack-mcp --doctor
|
|
428
|
-
```
|
|
429
|
-
2. If setup fails, run:
|
|
430
|
-
```bash
|
|
431
|
-
npx -y @jtalk22/slack-mcp --setup
|
|
432
|
-
```
|
|
433
|
-
3. Open an issue with full environment details:
|
|
434
|
-
- [Bug Report Template](https://github.com/jtalk22/slack-mcp-server/issues/new?template=bug_report.md)
|
|
435
|
-
- [Deployment Intake Template](https://github.com/jtalk22/slack-mcp-server/issues/new?template=deployment-intake.md)
|
|
436
|
-
4. For guided hosted rollout support:
|
|
437
|
-
- [GitHub Discussions](https://github.com/jtalk22/slack-mcp-server/discussions)
|
|
438
|
-
5. Check scope and response targets:
|
|
439
|
-
- [Support Boundaries](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/SUPPORT-BOUNDARIES.md)
|
|
440
|
-
- [Troubleshooting Guide](https://github.com/jtalk22/slack-mcp-server/blob/main/docs/TROUBLESHOOTING.md)
|
|
441
|
-
|
|
442
|
-
---
|
|
153
|
+
Details: [docs/DEPLOYMENT-MODES.md](docs/DEPLOYMENT-MODES.md)
|
|
443
154
|
|
|
444
155
|
## Troubleshooting
|
|
445
156
|
|
|
446
|
-
|
|
447
|
-
```bash
|
|
448
|
-
# macOS: Auto-refresh from Chrome
|
|
449
|
-
slack_refresh_tokens # In Claude
|
|
450
|
-
# Or: npm run tokens:auto
|
|
451
|
-
|
|
452
|
-
# Package setup wizard
|
|
453
|
-
npx -y @jtalk22/slack-mcp --setup
|
|
454
|
-
|
|
455
|
-
# Linux/Windows: Manual update
|
|
456
|
-
# Edit ~/.slack-mcp-tokens.json with fresh values
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
### DMs Not Showing
|
|
460
|
-
Use `discover_dms: true` to force discovery:
|
|
461
|
-
```
|
|
462
|
-
slack_list_conversations with discover_dms=true
|
|
463
|
-
```
|
|
464
|
-
This caches DM channel IDs for 24 hours.
|
|
465
|
-
|
|
466
|
-
### Chrome Extraction Fails
|
|
467
|
-
- Chrome must be **running** (not minimized to Dock)
|
|
468
|
-
- Slack tab must be open at `app.slack.com`
|
|
469
|
-
- You must be logged in
|
|
470
|
-
- In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
|
|
157
|
+
**Tokens expired:** Run `npx -y @jtalk22/slack-mcp --setup` or use `slack_refresh_tokens` in Claude (macOS).
|
|
471
158
|
|
|
472
|
-
|
|
473
|
-
1. Verify JSON syntax in config file
|
|
474
|
-
2. Check logs: `~/Library/Logs/Claude/mcp*.log`
|
|
475
|
-
3. Fully restart Claude (Cmd+Q, then reopen)
|
|
159
|
+
**DMs not showing:** Use `slack_list_conversations` with `discover_dms=true` to force discovery.
|
|
476
160
|
|
|
477
|
-
|
|
161
|
+
**Claude not seeing tools:** Verify JSON syntax in config, check logs at `~/Library/Logs/Claude/mcp*.log`, fully restart Claude (Cmd+Q).
|
|
478
162
|
|
|
479
|
-
|
|
163
|
+
More: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)
|
|
480
164
|
|
|
481
|
-
|
|
482
|
-
slack-mcp-server/
|
|
483
|
-
├── src/
|
|
484
|
-
│ ├── server.js # MCP server (stdio transport)
|
|
485
|
-
│ └── web-server.js # REST API + Web UI
|
|
486
|
-
├── lib/
|
|
487
|
-
│ ├── token-store.js # 4-layer persistence + atomic writes
|
|
488
|
-
│ ├── slack-client.js # API client, LRU cache, retry logic
|
|
489
|
-
│ ├── tools.js # MCP tool definitions
|
|
490
|
-
│ └── handlers.js # Tool implementations
|
|
491
|
-
├── public/
|
|
492
|
-
│ ├── index.html # Web UI
|
|
493
|
-
│ └── demo.html # Interactive demo
|
|
494
|
-
└── scripts/
|
|
495
|
-
└── token-cli.js # Token management CLI
|
|
496
|
-
```
|
|
165
|
+
## Docs
|
|
497
166
|
|
|
498
|
-
|
|
167
|
+
- [Setup Guide](docs/SETUP.md) — Token extraction and configuration
|
|
168
|
+
- [API Reference](docs/API.md) — All 16 tools with parameters and examples
|
|
169
|
+
- [Deployment Modes](docs/DEPLOYMENT-MODES.md) — stdio, web, hosted HTTP, Cloudflare Worker
|
|
170
|
+
- [Use Case Recipes](docs/USE_CASE_RECIPES.md) — 12 copy-paste prompts
|
|
171
|
+
- [Troubleshooting](docs/TROUBLESHOOTING.md) — Common issues and fixes
|
|
172
|
+
- [Compatibility](docs/COMPATIBILITY.md) — Client compatibility matrix
|
|
173
|
+
- [Support Boundaries](docs/SUPPORT-BOUNDARIES.md) — Scope and response targets
|
|
174
|
+
- [Docs Index](docs/INDEX.md) — Full documentation index
|
|
499
175
|
|
|
500
176
|
## Security
|
|
501
177
|
|
|
502
178
|
- Token files stored with `chmod 600` (owner-only)
|
|
503
179
|
- macOS Keychain provides encrypted backup
|
|
504
180
|
- Web server binds to localhost only
|
|
505
|
-
- Never commit tokens to version control
|
|
506
181
|
- API keys are cryptographically random (`crypto.randomBytes`)
|
|
507
|
-
|
|
508
|
-
---
|
|
509
|
-
|
|
510
|
-
## Platform Support
|
|
511
|
-
|
|
512
|
-
| Feature | macOS | Linux | Windows |
|
|
513
|
-
|---------|-------|-------|---------|
|
|
514
|
-
| MCP Server | Yes | Yes | Yes |
|
|
515
|
-
| Token File | Yes | Yes | Yes |
|
|
516
|
-
| Auto-Refresh from Chrome | Yes | No | No |
|
|
517
|
-
| Keychain Storage | Yes | No | No |
|
|
518
|
-
| Web UI | Yes | Yes | Yes |
|
|
519
|
-
|
|
520
|
-
---
|
|
182
|
+
- See [SECURITY.md](SECURITY.md) for vulnerability reporting
|
|
521
183
|
|
|
522
184
|
## Contributing
|
|
523
185
|
|
|
524
186
|
PRs welcome. Run `node --check` on modified files before submitting.
|
|
525
187
|
|
|
526
|
-
If this project saves you setup time, consider starring the repository.
|
|
527
|
-
|
|
528
|
-
---
|
|
529
|
-
|
|
530
188
|
## License
|
|
531
189
|
|
|
532
|
-
MIT
|
|
533
|
-
|
|
534
|
-
---
|
|
190
|
+
MIT — See [LICENSE](LICENSE)
|
|
535
191
|
|
|
536
192
|
## Disclaimer
|
|
537
193
|
|
|
538
|
-
This project
|
|
194
|
+
This project accesses Slack's Web API using browser session credentials. It is not affiliated with or endorsed by Slack Technologies, Inc. Slack workspace administrators should review their acceptable use policies.
|