@uniquedivine/mcp-slack 4.5.1 → 4.5.3
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 +113 -53
- package/docs/API.md +97 -17
- package/docs/DEPLOYMENT-MODES.md +2 -3
- package/docs/SETUP.md +78 -124
- package/docs/TROUBLESHOOTING.md +96 -233
- package/lib/handlers.js +12 -8
- package/lib/jiyuuMcpInfo.ts +92 -30
- package/lib/lifeboat.js +68 -3
- package/lib/message-ownership.js +28 -5
- package/lib/slack-client.js +53 -11
- package/lib/tools.js +16 -17
- package/lib/write-log.js +119 -0
- package/package.json +34 -5
- package/public/index.html +0 -4
- package/public/share.html +9 -10
- package/server.json +3 -3
package/docs/SETUP.md
CHANGED
|
@@ -1,28 +1,24 @@
|
|
|
1
1
|
# Setup Guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This guide covers `@uniquedivine/mcp-slack`, maintained by
|
|
4
|
+
[Unique Divine](https://uniquedivine.com). The [README](../README.md) has the
|
|
5
|
+
short version.
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
## Prerequisites
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
- Bun 1.4.3 or newer.
|
|
10
|
+
- A Slack account signed in at `app.slack.com` in a browser.
|
|
11
|
+
- On macOS only: Google Chrome, for automatic token extraction and refresh.
|
|
12
|
+
The server also stores tokens in the macOS Keychain. Other platforms use the
|
|
13
|
+
token file.
|
|
8
14
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
### Prerequisites
|
|
12
|
-
|
|
13
|
-
- Bun 1.4.3 or newer
|
|
14
|
-
- Google Chrome (for token extraction on macOS)
|
|
15
|
-
- macOS (for Keychain storage - other platforms use file storage only)
|
|
16
|
-
|
|
17
|
-
### 1. Install with Bun
|
|
15
|
+
## 1. Install
|
|
18
16
|
|
|
19
17
|
```bash
|
|
20
|
-
|
|
21
|
-
# or run it without a global install:
|
|
22
|
-
bunx @uniquedivine/mcp-slack@4.5.1 --version
|
|
18
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --version
|
|
23
19
|
```
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
To work from source instead:
|
|
26
22
|
|
|
27
23
|
```bash
|
|
28
24
|
git clone https://github.com/Unique-Divine/jiyuu.git
|
|
@@ -30,121 +26,104 @@ cd jiyuu/mcp/slack
|
|
|
30
26
|
bun install --frozen-lockfile
|
|
31
27
|
```
|
|
32
28
|
|
|
33
|
-
|
|
29
|
+
## 2. Verify the Install
|
|
30
|
+
|
|
31
|
+
Run these in an empty directory so that a local checkout can't shadow the
|
|
32
|
+
package:
|
|
34
33
|
|
|
35
34
|
```bash
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
bunx @uniquedivine/mcp-slack@4.5.
|
|
39
|
-
bunx @uniquedivine/mcp-slack@4.5.
|
|
40
|
-
bunx @uniquedivine/mcp-slack@4.5.1 --doctor
|
|
35
|
+
cd "$(mktemp -d)"
|
|
36
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --version
|
|
37
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --help
|
|
38
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --doctor
|
|
41
39
|
```
|
|
42
40
|
|
|
43
|
-
|
|
44
|
-
- `--version` and `--help` succeed.
|
|
45
|
-
- `--doctor` exits with one clear status:
|
|
46
|
-
- `0` ready
|
|
47
|
-
- `1` missing credentials
|
|
48
|
-
- `2` invalid/expired credentials
|
|
49
|
-
- `3` connectivity/runtime issue
|
|
50
|
-
- `--status` is read-only and never performs Chrome extraction.
|
|
41
|
+
Flags `--version` and `--help` exit `0`. Flag `--doctor` exits with one code:
|
|
51
42
|
|
|
52
|
-
|
|
43
|
+
| Code | Meaning |
|
|
44
|
+
|------|---------|
|
|
45
|
+
| `0` | Ready |
|
|
46
|
+
| `1` | Missing credentials |
|
|
47
|
+
| `2` | Invalid or expired credentials |
|
|
48
|
+
| `3` | Connectivity or runtime issue |
|
|
53
49
|
|
|
54
|
-
|
|
50
|
+
Flag `--status` is read-only and never runs Chrome extraction.
|
|
55
51
|
|
|
56
|
-
|
|
57
|
-
2. Navigate to https://app.slack.com and log in
|
|
58
|
-
3. Run:
|
|
59
|
-
```bash
|
|
60
|
-
bunx @uniquedivine/mcp-slack@4.5.1 --setup
|
|
61
|
-
```
|
|
52
|
+
## 3. Get Slack Tokens
|
|
62
53
|
|
|
63
|
-
|
|
54
|
+
Run the setup wizard:
|
|
64
55
|
|
|
65
56
|
```bash
|
|
66
|
-
|
|
57
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --setup
|
|
67
58
|
```
|
|
68
59
|
|
|
69
|
-
|
|
60
|
+
On macOS, the wizard reads the tokens from Chrome when Slack is open in a
|
|
61
|
+
Chrome tab. On other platforms, it asks you to paste them. From a source
|
|
62
|
+
checkout, `bun run tokens:auto` runs the macOS extraction and
|
|
63
|
+
`bun run tokens:refresh` prompts for manual values.
|
|
64
|
+
|
|
65
|
+
### Manual Extraction
|
|
66
|
+
|
|
67
|
+
1. Open <https://app.slack.com> in a browser and sign in.
|
|
68
|
+
2. Open DevTools with F12.
|
|
69
|
+
3. Under **Application** > **Cookies** > `https://app.slack.com`, copy the
|
|
70
|
+
value of cookie `d`. It starts with `xoxd-`.
|
|
71
|
+
4. In the **Console** tab, run:
|
|
70
72
|
|
|
71
|
-
1. Open https://app.slack.com in Chrome
|
|
72
|
-
2. Press F12 to open DevTools
|
|
73
|
-
3. Go to **Application** → **Cookies** → **https://app.slack.com**
|
|
74
|
-
4. Find the cookie named `d` and copy its value (starts with `xoxd-`)
|
|
75
|
-
5. Go to **Console** and paste:
|
|
76
73
|
```javascript
|
|
77
74
|
JSON.parse(localStorage.localConfig_v2).teams[Object.keys(JSON.parse(localStorage.localConfig_v2).teams)[0]].token
|
|
78
75
|
```
|
|
79
|
-
6. Copy the result (starts with `xoxc-`)
|
|
80
|
-
7. Run:
|
|
81
|
-
```bash
|
|
82
|
-
npm run tokens:refresh
|
|
83
|
-
```
|
|
84
|
-
And paste both values when prompted.
|
|
85
|
-
|
|
86
|
-
### 4. Configure Claude Desktop
|
|
87
|
-
|
|
88
|
-
**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
89
|
-
**Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`
|
|
90
76
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
"slack": {
|
|
95
|
-
"command": "bunx",
|
|
96
|
-
"args": ["@uniquedivine/mcp-slack@4.5.1"]
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
```
|
|
77
|
+
5. Copy the result. It starts with `xoxc-`.
|
|
78
|
+
6. Paste both values into `--setup`, or set environment variables
|
|
79
|
+
`SLACK_TOKEN` and `SLACK_COOKIE`.
|
|
101
80
|
|
|
102
|
-
|
|
81
|
+
Slack rotates these tokens every one to two weeks. Off macOS, repeat these
|
|
82
|
+
steps when a tool returns `invalid_auth` or `slack_auth_expired`.
|
|
103
83
|
|
|
104
|
-
|
|
84
|
+
## 4. Configure a Client
|
|
105
85
|
|
|
106
|
-
|
|
86
|
+
Claude Code:
|
|
107
87
|
|
|
108
88
|
```bash
|
|
109
|
-
claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.
|
|
89
|
+
claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.3
|
|
110
90
|
```
|
|
111
91
|
|
|
112
|
-
|
|
92
|
+
Claude Desktop reads file
|
|
93
|
+
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and
|
|
94
|
+
`%APPDATA%\Claude\claude_desktop_config.json` on Windows:
|
|
113
95
|
|
|
114
96
|
```json
|
|
115
97
|
{
|
|
116
98
|
"mcpServers": {
|
|
117
99
|
"slack": {
|
|
118
|
-
"type": "stdio",
|
|
119
100
|
"command": "bunx",
|
|
120
|
-
"args": ["@uniquedivine/mcp-slack@4.5.
|
|
101
|
+
"args": ["@uniquedivine/mcp-slack@4.5.3"]
|
|
121
102
|
}
|
|
122
103
|
}
|
|
123
104
|
}
|
|
124
105
|
```
|
|
125
106
|
|
|
126
|
-
Claude
|
|
107
|
+
Quit Claude Desktop fully and reopen it. On macOS, its log is file
|
|
108
|
+
`~/Library/Logs/Claude/mcp-server-slack.log`. The [README](../README.md#install)
|
|
109
|
+
lists the Codex and Cursor entries.
|
|
127
110
|
|
|
128
|
-
|
|
111
|
+
## 5. Verify the Connection
|
|
129
112
|
|
|
130
|
-
|
|
113
|
+
Call tool `slack_health_check`. It returns your user and team names.
|
|
131
114
|
|
|
132
|
-
##
|
|
115
|
+
## Keep Tokens Fresh While the Client Is Closed (macOS)
|
|
133
116
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
The MCP server auto-refreshes tokens every 4 hours while Claude is running. But if you keep Claude closed for a couple weeks, tokens expire silently — your next session opens with `invalid_auth`.
|
|
117
|
+
While it runs on macOS, the server checks token health every 4 hours. It reads
|
|
118
|
+
new tokens from Chrome only when the token file is more than 10 days old, or
|
|
119
|
+
when a read or send fails with `invalid_auth` or `token_expired`; edit and
|
|
120
|
+
delete tools don't retry. Neither path helps when `SLACK_TOKEN` and
|
|
121
|
+
`SLACK_COOKIE` are set, because those win over the token file. If no client
|
|
122
|
+
runs the server for a week or two, the tokens can expire before either case
|
|
123
|
+
happens. A LaunchAgent can run the refresh twice a day
|
|
124
|
+
whenever Chrome is open with a Slack tab.
|
|
144
125
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
Create `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
|
|
126
|
+
Create file `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
|
|
148
127
|
|
|
149
128
|
```xml
|
|
150
129
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
@@ -157,7 +136,7 @@ Create `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
|
|
|
157
136
|
<array>
|
|
158
137
|
<string>/bin/bash</string>
|
|
159
138
|
<string>-c</string>
|
|
160
|
-
<string>exec "$HOME/.bun/bin/bunx" @uniquedivine/mcp-slack@4.5.
|
|
139
|
+
<string>exec "$HOME/.bun/bin/bunx" @uniquedivine/mcp-slack@4.5.3 --refresh-tokens</string>
|
|
161
140
|
</array>
|
|
162
141
|
<key>StartCalendarInterval</key>
|
|
163
142
|
<array>
|
|
@@ -170,42 +149,17 @@ Create `~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist`:
|
|
|
170
149
|
</plist>
|
|
171
150
|
```
|
|
172
151
|
|
|
173
|
-
Load it:
|
|
152
|
+
Load it and check the log:
|
|
174
153
|
|
|
175
154
|
```bash
|
|
176
155
|
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.yourname.slack-token-refresh.plist
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
Check it ran:
|
|
180
|
-
|
|
181
|
-
```bash
|
|
182
156
|
tail /tmp/slack-token-refresh.log
|
|
183
157
|
```
|
|
184
158
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
### "No credentials found"
|
|
192
|
-
|
|
193
|
-
Run `bunx @uniquedivine/mcp-slack@4.5.1 --doctor` to confirm diagnostic code, then `bunx @uniquedivine/mcp-slack@4.5.1 --setup` with Slack open in Chrome.
|
|
194
|
-
|
|
195
|
-
### "invalid_auth" Error
|
|
196
|
-
|
|
197
|
-
Tokens have expired. Run `bunx @uniquedivine/mcp-slack@4.5.1 --doctor` and follow the suggested next action.
|
|
198
|
-
|
|
199
|
-
### MCP Server Not Loading
|
|
200
|
-
|
|
201
|
-
1. Check `~/.claude.json` syntax
|
|
202
|
-
2. Verify JSON syntax in your client's MCP config
|
|
203
|
-
3. Restart Claude Code
|
|
204
|
-
|
|
205
|
-
### Chrome Extraction Fails
|
|
159
|
+
LaunchAgents start without your shell profile, so the plist calls `bunx` by
|
|
160
|
+
its absolute path. With a Homebrew Bun install, use `/opt/homebrew/bin/bunx`.
|
|
161
|
+
Keep the version pin equal to the one in your client configuration. If Chrome
|
|
162
|
+
isn't running, the log shows "Failed to extract" and the tokens stay as they
|
|
163
|
+
were.
|
|
206
164
|
|
|
207
|
-
|
|
208
|
-
- Chrome is running (not just in dock)
|
|
209
|
-
- You have a Slack tab open (not the desktop app)
|
|
210
|
-
- You're logged into Slack in that tab
|
|
211
|
-
- In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
|
|
165
|
+
For problems, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
|
package/docs/TROUBLESHOOTING.md
CHANGED
|
@@ -1,186 +1,103 @@
|
|
|
1
1
|
# Troubleshooting Guide
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Fixes for common problems with `@uniquedivine/mcp-slack`. If none of these
|
|
4
|
+
help, open an issue in
|
|
5
|
+
[Unique-Divine/jiyuu](https://github.com/Unique-Divine/jiyuu/issues) with
|
|
6
|
+
`mcp/slack` in the title.
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
## Install Check
|
|
6
9
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
If first-run setup is failing, validate command resolution in a clean directory:
|
|
10
|
+
If first-run setup fails, check command resolution in an empty directory:
|
|
10
11
|
|
|
11
12
|
```bash
|
|
12
|
-
|
|
13
|
-
cd "$tmpdir"
|
|
13
|
+
cd "$(mktemp -d)"
|
|
14
14
|
bunx @uniquedivine/mcp-slack --version
|
|
15
15
|
bunx @uniquedivine/mcp-slack --help
|
|
16
16
|
bunx @uniquedivine/mcp-slack --doctor
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
- `1` missing credentials
|
|
24
|
-
- `2` invalid/expired credentials
|
|
25
|
-
- `3` connectivity/runtime issue
|
|
26
|
-
- `--status` is read-only and never attempts Chrome extraction.
|
|
27
|
-
|
|
28
|
-
If `--version` fails here, the issue is install/runtime path, not Slack credentials.
|
|
29
|
-
|
|
30
|
-
---
|
|
19
|
+
Flag `--doctor` exits `0` when ready, `1` for missing credentials, `2` for
|
|
20
|
+
invalid or expired credentials, and `3` for a connectivity or runtime issue.
|
|
21
|
+
If `--version` fails, the problem is the Bun install or `PATH`, not Slack
|
|
22
|
+
credentials.
|
|
31
23
|
|
|
32
|
-
##
|
|
24
|
+
## Expired Tokens
|
|
33
25
|
|
|
34
|
-
|
|
26
|
+
**Symptom:** Tools return `invalid_auth`, `token_expired`, or
|
|
27
|
+
`slack_auth_expired`.
|
|
35
28
|
|
|
36
|
-
|
|
29
|
+
**Cause:** Slack rotates browser session tokens (`xoxc-` and `xoxd-`) every
|
|
30
|
+
one to two weeks.
|
|
37
31
|
|
|
38
|
-
|
|
32
|
+
The server looks for tokens in this order:
|
|
39
33
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
34
|
+
1. Environment variables `SLACK_TOKEN` and `SLACK_COOKIE`.
|
|
35
|
+
2. File `~/.slack-mcp-tokens.json`.
|
|
36
|
+
3. The macOS Keychain.
|
|
37
|
+
4. Chrome extraction, on macOS only.
|
|
43
38
|
|
|
44
|
-
**
|
|
39
|
+
**Fix on macOS:** With Slack open in a Chrome tab, call tool
|
|
40
|
+
`slack_refresh_tokens`, or run
|
|
41
|
+
`bunx @uniquedivine/mcp-slack --refresh-tokens`.
|
|
45
42
|
|
|
46
|
-
**
|
|
43
|
+
**Fix everywhere else:** Chrome auto-refresh runs only on macOS. Sign in to
|
|
44
|
+
Slack in a browser, run `bunx @uniquedivine/mcp-slack --setup`, and paste
|
|
45
|
+
fresh values. [Manual Extraction](SETUP.md#manual-extraction) shows where to
|
|
46
|
+
find them. Then reconnect the MCP server.
|
|
47
47
|
|
|
48
|
-
If
|
|
49
|
-
|
|
50
|
-
2. Verify the user exists: `slack_list_users`
|
|
48
|
+
If `SLACK_TOKEN` and `SLACK_COOKIE` are set, they win over the token file.
|
|
49
|
+
Update both or unset both; `--setup` alone has no effect while they are set.
|
|
51
50
|
|
|
52
|
-
|
|
51
|
+
## Edit or Delete Refused
|
|
53
52
|
|
|
54
|
-
|
|
53
|
+
**`message_too_old`:** Tools `slack_update_message` and
|
|
54
|
+
`slack_delete_message` refuse messages older than 7 days. Set
|
|
55
|
+
`SLACK_MCP_EDIT_DELETE_MAX_AGE_HOURS` on the server to change the window, or
|
|
56
|
+
ask for `slack_update_message_unsafe` or `slack_delete_message_unsafe`, which
|
|
57
|
+
skip only the age check.
|
|
55
58
|
|
|
56
|
-
|
|
59
|
+
**`unknown_tool` for an `_unsafe` tool over HTTP:** The HTTP server hides
|
|
60
|
+
the `_unsafe` tools unless `SLACK_MCP_ENABLE_UNSAFE_TOOLS=true`.
|
|
57
61
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
- Second retry: Wait 10 seconds
|
|
63
|
-
- Third retry: Wait 15 seconds
|
|
64
|
-
|
|
65
|
-
If you still hit limits, reduce batch sizes:
|
|
66
|
-
```
|
|
67
|
-
slack_list_conversations limit=50
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
---
|
|
71
|
-
|
|
72
|
-
## Token Expiration
|
|
73
|
-
|
|
74
|
-
**Symptom:** `invalid_auth` or `token_expired` errors.
|
|
75
|
-
|
|
76
|
-
**Cause:** Browser tokens (xoxc/xoxd) expire after 1-2 weeks.
|
|
77
|
-
|
|
78
|
-
**Solution:** The server has 4 layers of token recovery:
|
|
79
|
-
|
|
80
|
-
1. **Environment variables** - From MCP config (Claude Desktop)
|
|
81
|
-
2. **Token file** - `~/.slack-mcp-tokens.json`
|
|
82
|
-
3. **macOS Keychain** - Encrypted persistent storage
|
|
83
|
-
4. **Chrome auto-extraction** - Fallback when all else fails
|
|
84
|
-
|
|
85
|
-
**To refresh tokens:**
|
|
86
|
-
```bash
|
|
87
|
-
# Option 1: In Claude Code/Desktop
|
|
88
|
-
slack_refresh_tokens
|
|
62
|
+
**`not_own_message` or `text_mismatch`:** The tools act only on your own
|
|
63
|
+
messages, and argument `expected_text` must match the message's current text.
|
|
64
|
+
Re-read the message with `slack_conversations_history` or `slack_get_thread`
|
|
65
|
+
and pass its text.
|
|
89
66
|
|
|
90
|
-
#
|
|
91
|
-
bunx @uniquedivine/mcp-slack --setup
|
|
67
|
+
[API.md](API.md#slack_delete_message) lists every error code.
|
|
92
68
|
|
|
93
|
-
|
|
94
|
-
bunx @uniquedivine/mcp-slack --doctor
|
|
95
|
-
|
|
96
|
-
# Option 4: Repo CLI
|
|
97
|
-
npm run tokens:auto
|
|
98
|
-
|
|
99
|
-
# Option 5: Manual
|
|
100
|
-
npm run tokens:refresh
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## Web Server Issues
|
|
106
|
-
|
|
107
|
-
### Server Stops When Terminal Closes
|
|
108
|
-
|
|
109
|
-
**Solution:** Use LaunchAgent for persistence:
|
|
110
|
-
|
|
111
|
-
```bash
|
|
112
|
-
# Create LaunchAgent
|
|
113
|
-
cat > ~/Library/LaunchAgents/com.slack-web-api.plist << 'EOF'
|
|
114
|
-
<?xml version="1.0" encoding="UTF-8"?>
|
|
115
|
-
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
|
116
|
-
<plist version="1.0">
|
|
117
|
-
<dict>
|
|
118
|
-
<key>Label</key>
|
|
119
|
-
<string>com.slack-web-api</string>
|
|
120
|
-
<key>ProgramArguments</key>
|
|
121
|
-
<array>
|
|
122
|
-
<string>/Users/YOUR_USERNAME/.bun/bin/bunx</string>
|
|
123
|
-
<string>@uniquedivine/mcp-slack@4.5.1</string>
|
|
124
|
-
<string>web</string>
|
|
125
|
-
</array>
|
|
126
|
-
<key>RunAtLoad</key>
|
|
127
|
-
<true/>
|
|
128
|
-
<key>KeepAlive</key>
|
|
129
|
-
<true/>
|
|
130
|
-
</dict>
|
|
131
|
-
</plist>
|
|
132
|
-
EOF
|
|
133
|
-
|
|
134
|
-
launchctl load ~/Library/LaunchAgents/com.slack-web-api.plist
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
### API Key Invalid
|
|
138
|
-
|
|
139
|
-
The web server generates a unique API key on first run, stored in `~/.slack-mcp-api-key`.
|
|
140
|
-
|
|
141
|
-
The key is printed to the console when you start the server:
|
|
142
|
-
```
|
|
143
|
-
Dashboard: http://localhost:3000/?key=smcp_xxxxxxxxxxxx
|
|
144
|
-
API Key: smcp_xxxxxxxxxxxx
|
|
145
|
-
```
|
|
69
|
+
## DMs Missing
|
|
146
70
|
|
|
147
|
-
|
|
148
|
-
```bash
|
|
149
|
-
SLACK_API_KEY=your-custom-key npm run web
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
### Can't Connect to localhost:3000
|
|
153
|
-
|
|
154
|
-
Check if the server is running:
|
|
155
|
-
```bash
|
|
156
|
-
# Get your API key from ~/.slack-mcp-api-key
|
|
157
|
-
curl http://localhost:3000/health -H "Authorization: Bearer $(cat ~/.slack-mcp-api-key)"
|
|
158
|
-
```
|
|
71
|
+
**Symptom:** `slack_list_conversations` returns channels but no DMs.
|
|
159
72
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
73
|
+
Slack's `conversations.list` method doesn't return DMs for `xoxc-` tokens. By
|
|
74
|
+
default, `slack_list_conversations` adds DMs only from its cache in file
|
|
75
|
+
`~/.slack-mcp-dm-cache.json`, and the server ignores that cache once it is
|
|
76
|
+
more than 24 hours old. To rebuild it, call the tool with
|
|
77
|
+
`discover_dms: true` and `types: "im,mpim"`. The server then reads the first
|
|
78
|
+
200 users from `users.list`, calls `conversations.open` for each one, 50 ms
|
|
79
|
+
apart, and saves the DMs it finds.
|
|
164
80
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
cat /tmp/slack-web-api.error.log
|
|
169
|
-
```
|
|
81
|
+
Discovery is slow and can hit rate limits. It also calls `conversations.open`
|
|
82
|
+
for users you have never messaged, which can add empty DMs to your Slack
|
|
83
|
+
sidebar.
|
|
170
84
|
|
|
171
|
-
|
|
85
|
+
## Rate Limits
|
|
172
86
|
|
|
173
|
-
|
|
87
|
+
**Symptom:** `ratelimited` errors.
|
|
174
88
|
|
|
175
|
-
|
|
89
|
+
The Slack client in file `lib/slack-client.js` waits for Slack's
|
|
90
|
+
`Retry-After` header, or 5 seconds without one, and retries up to 3 times
|
|
91
|
+
with a longer wait each time. If you still hit limits, lower `limit` on list
|
|
92
|
+
calls.
|
|
176
93
|
|
|
177
|
-
|
|
178
|
-
SLACK_MCP_HTTP_AUTH_TOKEN=change-this
|
|
179
|
-
```
|
|
94
|
+
## HTTP Server Returns 503 or 401
|
|
180
95
|
|
|
181
|
-
|
|
96
|
+
Endpoint `/mcp` on the HTTP server (`bun src/cli.js http`) requires a bearer
|
|
97
|
+
token.
|
|
182
98
|
|
|
183
|
-
|
|
99
|
+
- `503 http_auth_token_missing`: set `SLACK_MCP_HTTP_AUTH_TOKEN`.
|
|
100
|
+
- `401 unauthorized`: the request has no bearer token or the wrong one.
|
|
184
101
|
|
|
185
102
|
```bash
|
|
186
103
|
curl http://localhost:3000/mcp \
|
|
@@ -189,101 +106,47 @@ curl http://localhost:3000/mcp \
|
|
|
189
106
|
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
|
|
190
107
|
```
|
|
191
108
|
|
|
192
|
-
For local
|
|
193
|
-
|
|
194
|
-
```bash
|
|
195
|
-
SLACK_MCP_HTTP_INSECURE=1 bun src/server-http.js
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
---
|
|
199
|
-
|
|
200
|
-
## Claude Desktop Issues
|
|
201
|
-
|
|
202
|
-
### Slack Tools Not Appearing
|
|
203
|
-
|
|
204
|
-
**Symptom:** Claude Desktop doesn't show Slack tools after adding config.
|
|
205
|
-
|
|
206
|
-
**Solutions:**
|
|
207
|
-
|
|
208
|
-
1. **Fully restart Claude Desktop:**
|
|
209
|
-
- Cmd+Q (don't just close window)
|
|
210
|
-
- Reopen the app
|
|
211
|
-
|
|
212
|
-
2. **Check config syntax:**
|
|
213
|
-
```bash
|
|
214
|
-
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
3. **Check MCP logs:**
|
|
218
|
-
```bash
|
|
219
|
-
cat ~/Library/Logs/Claude/mcp-server-slack.log
|
|
220
|
-
```
|
|
109
|
+
For local testing only, `SLACK_MCP_HTTP_INSECURE=1` turns the check off.
|
|
221
110
|
|
|
222
|
-
|
|
223
|
-
```bash
|
|
224
|
-
which bunx
|
|
225
|
-
# Use this full path in config
|
|
226
|
-
```
|
|
111
|
+
## Web Server Problems
|
|
227
112
|
|
|
228
|
-
|
|
113
|
+
The web server writes its API key to file `~/.slack-mcp-api-key`, and the
|
|
114
|
+
startup log masks all but the first 8 characters. If `SLACK_API_KEY` is set,
|
|
115
|
+
the server uses it instead of the file. This check picks the same key:
|
|
229
116
|
|
|
230
|
-
**Check the log:**
|
|
231
117
|
```bash
|
|
232
|
-
|
|
118
|
+
API_KEY="${SLACK_API_KEY:-$(cat ~/.slack-mcp-api-key)}"
|
|
119
|
+
curl http://localhost:3000/health -H "Authorization: Bearer $API_KEY"
|
|
233
120
|
```
|
|
234
121
|
|
|
235
|
-
|
|
236
|
-
-
|
|
237
|
-
- Missing tokens in env section
|
|
238
|
-
- Invalid JSON syntax in config
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
|
-
## Chrome Extraction Fails
|
|
243
|
-
|
|
244
|
-
**Symptom:** `slack_refresh_tokens` returns "Could not extract from Chrome"
|
|
245
|
-
|
|
246
|
-
**Requirements:**
|
|
247
|
-
1. Google Chrome must be running (not just in Dock)
|
|
248
|
-
2. Have a Slack tab open at `app.slack.com` (not desktop app)
|
|
249
|
-
3. Be logged into Slack in that tab
|
|
250
|
-
4. In Chrome menu, enable `View > Developer > Allow JavaScript from Apple Events`
|
|
251
|
-
5. Grant accessibility permissions to Terminal/Claude
|
|
252
|
-
|
|
253
|
-
**Check permissions:**
|
|
254
|
-
System Preferences → Privacy & Security → Accessibility → Ensure Terminal is enabled
|
|
255
|
-
|
|
256
|
-
---
|
|
257
|
-
|
|
258
|
-
## Why Browser Tokens Instead of Slack App?
|
|
259
|
-
|
|
260
|
-
**Question:** Why not just create a Slack app with proper OAuth?
|
|
122
|
+
To keep it running after the terminal closes on macOS, use the LaunchAgent
|
|
123
|
+
in [WEB-API.md](WEB-API.md#auto-start-on-login).
|
|
261
124
|
|
|
262
|
-
|
|
125
|
+
## Tools Missing in Claude Desktop
|
|
263
126
|
|
|
264
|
-
|
|
127
|
+
1. Quit Claude Desktop fully and reopen it.
|
|
128
|
+
2. Check the config syntax:
|
|
129
|
+
`python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json`.
|
|
130
|
+
3. Read file `~/Library/Logs/Claude/mcp-server-slack.log`.
|
|
131
|
+
4. If the log says Bun wasn't found, put the absolute path from
|
|
132
|
+
`which bunx` in `command`.
|
|
265
133
|
|
|
266
|
-
|
|
267
|
-
- ✅ Full access to all your conversations
|
|
268
|
-
- ✅ No per-conversation authorization needed
|
|
269
|
-
- ❌ Tokens expire every 1-2 weeks
|
|
270
|
-
- ❌ Requires Chrome for token extraction
|
|
134
|
+
## Chrome Extraction Fails (macOS)
|
|
271
135
|
|
|
272
|
-
|
|
136
|
+
**Symptom:** `slack_refresh_tokens` can't extract tokens from Chrome.
|
|
273
137
|
|
|
274
|
-
|
|
138
|
+
Check that:
|
|
275
139
|
|
|
276
|
-
1.
|
|
277
|
-
|
|
278
|
-
|
|
140
|
+
1. Chrome is running with a Slack tab at `app.slack.com`, not the desktop
|
|
141
|
+
app, and you are signed in.
|
|
142
|
+
2. **View** > **Developer** > **Allow JavaScript from Apple Events** is on.
|
|
143
|
+
Or set `SLACK_MCP_EXTRACTION_MODE=leveldb` to skip AppleScript.
|
|
144
|
+
3. If Chrome uses a non-default profile or location, set
|
|
145
|
+
`SLACK_MCP_CHROME_PROFILE` or `SLACK_MCP_CHROME_USER_DATA_DIR`.
|
|
279
146
|
|
|
280
|
-
|
|
281
|
-
```bash
|
|
282
|
-
cd jiyuu/mcp/slack
|
|
283
|
-
bun src/server.js # Should say "running"
|
|
284
|
-
```
|
|
147
|
+
## Why Browser Tokens Instead of a Slack App?
|
|
285
148
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
149
|
+
A Slack app needs workspace approval and OAuth scopes, and it can't read your
|
|
150
|
+
DMs the way you see them. Session tokens give the server the same access you
|
|
151
|
+
have in Slack's web client. The cost is token rotation every one to two
|
|
152
|
+
weeks, which you refresh by hand off macOS.
|