@uniquedivine/mcp-slack 4.5.2 → 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 +66 -17
- package/docs/DEPLOYMENT-MODES.md +2 -3
- package/docs/SETUP.md +78 -124
- package/docs/TROUBLESHOOTING.md +96 -233
- package/lib/jiyuuMcpInfo.ts +92 -30
- package/lib/tools.js +16 -17
- package/package.json +34 -5
- package/public/index.html +0 -4
- package/public/share.html +9 -10
- package/server.json +3 -3
package/README.md
CHANGED
|
@@ -1,8 +1,11 @@
|
|
|
1
1
|
# Slack MCP
|
|
2
2
|
|
|
3
|
-
Read Slack channels, threads and search results
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Read Slack channels, DMs, threads, and search results through your own
|
|
4
|
+
browser session, and send, edit, or delete your messages when you ask. The
|
|
5
|
+
server needs no Slack app and no admin approval.
|
|
6
|
+
|
|
7
|
+
Maintained by [Unique Divine](https://uniquedivine.com) in
|
|
8
|
+
[Unique-Divine/jiyuu](https://github.com/Unique-Divine/jiyuu).
|
|
6
9
|
|
|
7
10
|
## Install
|
|
8
11
|
|
|
@@ -11,8 +14,8 @@ in through a browser. Store credentials once, then run the published package
|
|
|
11
14
|
with an exact version pin:
|
|
12
15
|
|
|
13
16
|
```sh
|
|
14
|
-
bunx @uniquedivine/mcp-slack@4.5.
|
|
15
|
-
bunx @uniquedivine/mcp-slack@4.5.
|
|
17
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --setup
|
|
18
|
+
bunx @uniquedivine/mcp-slack@4.5.3
|
|
16
19
|
```
|
|
17
20
|
|
|
18
21
|
Flag `--setup` writes file `~/.slack-mcp-tokens.json`. To pass environment
|
|
@@ -25,7 +28,7 @@ changes on `main`. The version pin selects the exact reviewed release that runs.
|
|
|
25
28
|
### Claude Code
|
|
26
29
|
|
|
27
30
|
```sh
|
|
28
|
-
claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.
|
|
31
|
+
claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.3
|
|
29
32
|
```
|
|
30
33
|
|
|
31
34
|
### Codex
|
|
@@ -35,7 +38,7 @@ Add this entry to file `~/.codex/config.toml`:
|
|
|
35
38
|
```toml
|
|
36
39
|
[mcp_servers.slack]
|
|
37
40
|
command = "bunx"
|
|
38
|
-
args = ["@uniquedivine/mcp-slack@4.5.
|
|
41
|
+
args = ["@uniquedivine/mcp-slack@4.5.3"]
|
|
39
42
|
```
|
|
40
43
|
|
|
41
44
|
### Cursor
|
|
@@ -48,7 +51,7 @@ a project:
|
|
|
48
51
|
"mcpServers": {
|
|
49
52
|
"slack": {
|
|
50
53
|
"command": "bunx",
|
|
51
|
-
"args": ["@uniquedivine/mcp-slack@4.5.
|
|
54
|
+
"args": ["@uniquedivine/mcp-slack@4.5.3"]
|
|
52
55
|
}
|
|
53
56
|
}
|
|
54
57
|
}
|
|
@@ -58,47 +61,113 @@ a project:
|
|
|
58
61
|
|
|
59
62
|
1. Find the newest version with command
|
|
60
63
|
`npm view @uniquedivine/mcp-slack version`.
|
|
61
|
-
2. Change the `@4.5.
|
|
64
|
+
2. Change the `@4.5.3` pin in the client configuration to that version.
|
|
62
65
|
3. Restart the MCP server in the client, or restart the client. In Claude
|
|
63
66
|
Code, run `/mcp` and reconnect the server. Command `bunx` downloads the new
|
|
64
67
|
version on the next launch.
|
|
65
68
|
|
|
66
69
|
The token store and workflow files live in your home directory, so an update
|
|
67
|
-
needs no new credentials.
|
|
70
|
+
needs no new credentials. Tool `mcp_info` reports the running version and
|
|
71
|
+
whether a newer release exists.
|
|
68
72
|
|
|
69
|
-
##
|
|
73
|
+
## Tools
|
|
70
74
|
|
|
71
|
-
|
|
72
|
-
|
|
75
|
+
The server has 25 Slack tools. The stdio server also lists tool `mcp_info`.
|
|
76
|
+
[docs/API.md](docs/API.md) documents parameters, results, and errors.
|
|
73
77
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
78
|
+
| Group | Tools |
|
|
79
|
+
|-------|-------|
|
|
80
|
+
| Session | `slack_health_check`, `slack_token_status`, `slack_refresh_tokens` |
|
|
81
|
+
| Read | `slack_list_conversations`, `slack_conversations_history`, `slack_get_full_conversation`, `slack_get_thread`, `slack_search_messages`, `slack_conversations_unreads`, `slack_users_info`, `slack_list_users`, `slack_users_search` |
|
|
82
|
+
| Write | `slack_send_message`, `slack_update_message`, `slack_update_message_unsafe`, `slack_delete_message`, `slack_delete_message_unsafe`, `slack_add_reaction`, `slack_remove_reaction`, `slack_conversations_mark` |
|
|
83
|
+
| Workflow profiles | `slack_workflow_save`, `slack_workflows` |
|
|
84
|
+
| Hosted only | `slack_smart_search`, `slack_catch_me_up`, `slack_triage` |
|
|
85
|
+
|
|
86
|
+
The three hosted-only tools call nothing locally and return error
|
|
87
|
+
`tool_requires_hosted`.
|
|
88
|
+
|
|
89
|
+
### Edit and Delete
|
|
90
|
+
|
|
91
|
+
Tools `slack_update_message` and `slack_delete_message` act only on your own
|
|
92
|
+
messages. Before each write, the tool checks that:
|
|
93
|
+
|
|
94
|
+
- the signed-in user wrote the message;
|
|
95
|
+
- argument `expected_text` matches the message's current text;
|
|
96
|
+
- the message is no older than 7 days.
|
|
79
97
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
98
|
+
Environment variable `SLACK_MCP_EDIT_DELETE_MAX_AGE_HOURS` changes the window
|
|
99
|
+
from its default of 168 hours. Tools `slack_update_message_unsafe` and
|
|
100
|
+
`slack_delete_message_unsafe` skip only the age check, for cleanup of older
|
|
101
|
+
messages that you ask for by name. Keep both off your client's auto-allow list
|
|
102
|
+
so that you confirm each call.
|
|
103
|
+
|
|
104
|
+
The stdio server lists the `_unsafe` tools. The HTTP server
|
|
105
|
+
(`bun src/cli.js http`) hides them unless environment variable
|
|
106
|
+
`SLACK_MCP_ENABLE_UNSAFE_TOOLS` is `true`, because HTTP clients may not prompt
|
|
107
|
+
before a call.
|
|
108
|
+
|
|
109
|
+
Each edit or delete attempt writes one `slack-mcp write` JSON line to stderr
|
|
110
|
+
with the tool, channel, timestamp, status, error code, and message age. The
|
|
111
|
+
line never holds tokens, cookies, or message text.
|
|
112
|
+
[Write Log](docs/API.md#write-log) lists the fields.
|
|
84
113
|
|
|
85
114
|
## Authenticate
|
|
86
115
|
|
|
87
|
-
|
|
116
|
+
The server uses your browser session tokens: an `xoxc-` token and the `xoxd-`
|
|
117
|
+
value of cookie `d`. Run the setup helper, which stores them outside the
|
|
118
|
+
source tree:
|
|
88
119
|
|
|
89
120
|
```sh
|
|
90
|
-
|
|
91
|
-
bun src/cli.js --setup
|
|
121
|
+
bunx @uniquedivine/mcp-slack@4.5.3 --setup
|
|
92
122
|
```
|
|
93
123
|
|
|
94
|
-
|
|
95
|
-
`~/.slack-mcp-tokens.json
|
|
96
|
-
|
|
97
|
-
|
|
124
|
+
Environment variables `SLACK_TOKEN` and `SLACK_COOKIE` take precedence over
|
|
125
|
+
file `~/.slack-mcp-tokens.json`. Do not commit tokens, cookies, browser
|
|
126
|
+
profiles, or local exports.
|
|
127
|
+
|
|
128
|
+
Slack rotates session tokens every one to two weeks. On macOS, the server
|
|
129
|
+
reads fresh tokens from Chrome in three cases:
|
|
130
|
+
|
|
131
|
+
- A Slack call fails with `invalid_auth` or `token_expired`. The server
|
|
132
|
+
extracts new tokens and retries the call once. Edit and delete tools skip
|
|
133
|
+
this retry on purpose, so that a write never runs under a different
|
|
134
|
+
session. Refresh the tokens, then call the tool again.
|
|
135
|
+
- A health check, which runs every 4 hours, finds that the tokens in file
|
|
136
|
+
`~/.slack-mcp-tokens.json` are more than 10 days old. The server tries at
|
|
137
|
+
most once an hour. Tokens from environment variables have no recorded age,
|
|
138
|
+
so this check never refreshes them.
|
|
139
|
+
- You call tool `slack_refresh_tokens` or run `--refresh-tokens`.
|
|
140
|
+
|
|
141
|
+
Each case needs Chrome running with a signed-in Slack tab at `app.slack.com`.
|
|
142
|
+
Extraction writes file `~/.slack-mcp-tokens.json`. If you set `SLACK_TOKEN`
|
|
143
|
+
and `SLACK_COOKIE`, the server keeps using them, so none of these cases
|
|
144
|
+
helps. Update both variables or unset both.
|
|
145
|
+
|
|
146
|
+
Chrome auto-refresh runs only on macOS. On Linux, Windows, and WSL, refresh by
|
|
147
|
+
hand when a tool returns `invalid_auth` or `slack_auth_expired`:
|
|
148
|
+
|
|
149
|
+
1. Sign in to Slack at <https://app.slack.com> in a browser.
|
|
150
|
+
2. Run `bunx @uniquedivine/mcp-slack@4.5.3 --setup` and paste the token and
|
|
151
|
+
cookie when it asks. [Manual Extraction](docs/SETUP.md#manual-extraction)
|
|
152
|
+
shows where to find them.
|
|
153
|
+
3. If you set `SLACK_TOKEN` and `SLACK_COOKIE`, update both or unset both.
|
|
154
|
+
Setup alone has no effect while they are set.
|
|
155
|
+
4. Reconnect the MCP server.
|
|
156
|
+
|
|
157
|
+
## Install From Source
|
|
158
|
+
|
|
159
|
+
Requirements: Git and Bun 1.4.3 or newer. Linked executables, package scripts,
|
|
160
|
+
tests, and CI use Bun directly; no Node installation is needed.
|
|
98
161
|
|
|
99
|
-
|
|
162
|
+
```sh
|
|
163
|
+
git clone https://github.com/Unique-Divine/jiyuu.git
|
|
164
|
+
cd jiyuu
|
|
165
|
+
just --justfile mcp/slack/justfile install
|
|
166
|
+
```
|
|
100
167
|
|
|
101
|
-
|
|
168
|
+
Without Just, run `bun install --frozen-lockfile` inside `mcp/slack`. Command
|
|
169
|
+
`just link` runs `bun link`, which points command `slack-mcp` and the other
|
|
170
|
+
package executables at this checkout. Then configure the client:
|
|
102
171
|
|
|
103
172
|
```json
|
|
104
173
|
{
|
|
@@ -108,9 +177,9 @@ After `just link`, the existing configuration remains valid:
|
|
|
108
177
|
}
|
|
109
178
|
```
|
|
110
179
|
|
|
111
|
-
For a direct source launch,
|
|
112
|
-
Restart the MCP connection after
|
|
113
|
-
connected Slack identity before
|
|
180
|
+
For a direct source launch, run `bun` with the absolute path to `src/cli.js`.
|
|
181
|
+
Restart the MCP connection after you relink or change code. Check the
|
|
182
|
+
connected Slack identity with `slack_health_check` before you write.
|
|
114
183
|
|
|
115
184
|
## Develop
|
|
116
185
|
|
|
@@ -121,27 +190,18 @@ just check
|
|
|
121
190
|
just run
|
|
122
191
|
```
|
|
123
192
|
|
|
124
|
-
Run these commands from `mcp/slack`. The
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
errors. TypeScript conversion and native `bun check` coverage are follow-ups.
|
|
129
|
-
|
|
130
|
-
The inherited Dockerfile still describes the upstream Node image and is not
|
|
131
|
-
the supported Jiyuu installation. Its conversion is tracked separately.
|
|
193
|
+
Run these commands from `mcp/slack`. The `bun:test` suite covers tool and
|
|
194
|
+
handler parity, rich message fields, edit and delete guards, the write log,
|
|
195
|
+
and authentication errors without sending Slack messages. Recipe `check`
|
|
196
|
+
builds the entrypoints to an ignored cache to catch import and syntax errors.
|
|
132
197
|
|
|
133
|
-
HTTP and web modes
|
|
134
|
-
`bun src/cli.js web`.
|
|
135
|
-
|
|
136
|
-
recommendation to deploy or purchase the original hosted service.
|
|
198
|
+
HTTP and web modes run through `bun src/cli.js http` and
|
|
199
|
+
`bun src/cli.js web`. [docs/WEB-API.md](docs/WEB-API.md) covers the web mode.
|
|
200
|
+
The Dockerfile targets a Node image and is not a supported install path.
|
|
137
201
|
|
|
138
202
|
Report issues in [Unique-Divine/jiyuu](https://github.com/Unique-Divine/jiyuu/issues)
|
|
139
|
-
with `mcp/slack` in the title.
|
|
140
|
-
`@jtalk22/slack-mcp` 4.4.3. Package metadata `jiyuu.upstream` in file
|
|
141
|
-
`package.json` records that baseline.
|
|
203
|
+
with `mcp/slack` in the title.
|
|
142
204
|
|
|
143
|
-
##
|
|
205
|
+
## License
|
|
144
206
|
|
|
145
|
-
|
|
146
|
-
`jtalk22/slack-mcp-server`. [IMPORT.json](IMPORT.json) pins the source commit.
|
|
147
|
-
The original [MIT license and copyright notice](LICENSE) are retained.
|
|
207
|
+
MIT. See [LICENSE](LICENSE).
|
package/docs/API.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# API Reference
|
|
2
2
|
|
|
3
|
+
Parameters, results, and errors for the 25 Slack tools in
|
|
4
|
+
`@uniquedivine/mcp-slack`, plus tool `mcp_info`. Over HTTP, the `_unsafe`
|
|
5
|
+
tools need `SLACK_MCP_ENABLE_UNSAFE_TOOLS=true`.
|
|
6
|
+
|
|
3
7
|
## Tools
|
|
4
8
|
|
|
5
9
|
### slack_health_check
|
|
@@ -14,8 +18,8 @@ Check if Slack tokens are valid.
|
|
|
14
18
|
"status": "ok",
|
|
15
19
|
"code": "ok",
|
|
16
20
|
"message": "Slack auth valid",
|
|
17
|
-
"user": "
|
|
18
|
-
"team": "
|
|
21
|
+
"user": "unique",
|
|
22
|
+
"team": "Example Workspace",
|
|
19
23
|
"token_source": "environment",
|
|
20
24
|
"token_updated": "2026-01-03T00:00:00Z"
|
|
21
25
|
}
|
|
@@ -70,8 +74,8 @@ Force refresh tokens from Chrome.
|
|
|
70
74
|
"status": "ok",
|
|
71
75
|
"code": "refreshed",
|
|
72
76
|
"message": "Tokens refreshed from Chrome.",
|
|
73
|
-
"user": "
|
|
74
|
-
"team": "
|
|
77
|
+
"user": "unique",
|
|
78
|
+
"team": "Example Workspace"
|
|
75
79
|
}
|
|
76
80
|
```
|
|
77
81
|
|
|
@@ -149,20 +153,20 @@ Get messages from a channel or DM.
|
|
|
149
153
|
}
|
|
150
154
|
```
|
|
151
155
|
|
|
152
|
-
`include_rich_message_fields` changes
|
|
153
|
-
already returns on
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
156
|
+
Parameter `include_rich_message_fields` changes only the output shape. It
|
|
157
|
+
adds fields Slack already returns on each message: `attachments`, `blocks`,
|
|
158
|
+
`files`, `reactions`, `metadata`, `subtype`, `bot_id`, `app_id`, and `team`.
|
|
159
|
+
Fields `subtype`, `bot_id`, and `app_id` mark bot and app messages. Field
|
|
160
|
+
`blocks` can be large, so the parameter is off by default.
|
|
157
161
|
|
|
158
|
-
`include_all_metadata` is a
|
|
159
|
-
|
|
160
|
-
`metadata.event_type
|
|
161
|
-
|
|
162
|
+
Parameter `include_all_metadata` is a separate Slack request flag. It adds the
|
|
163
|
+
full `event_payload` inside a message's `metadata`; without it, you get only
|
|
164
|
+
`metadata.event_type`. Set `include_rich_message_fields` to see `metadata` at
|
|
165
|
+
all, and add `include_all_metadata` for the full payload.
|
|
162
166
|
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
`
|
|
167
|
+
Slack's search API doesn't return these rich fields on matches, only `team`.
|
|
168
|
+
To read rich content for a search hit, call `slack_conversations_history` or
|
|
169
|
+
`slack_get_thread` with the match's channel and timestamp.
|
|
166
170
|
|
|
167
171
|
---
|
|
168
172
|
|
|
@@ -196,7 +200,7 @@ Export full conversation with threads.
|
|
|
196
200
|
"oldest": "2025-12-01T00:00:00Z",
|
|
197
201
|
"latest": "now"
|
|
198
202
|
},
|
|
199
|
-
"saved_to": "/Users/
|
|
203
|
+
"saved_to": "/Users/you/export.json",
|
|
200
204
|
"messages": [...]
|
|
201
205
|
}
|
|
202
206
|
```
|
|
@@ -658,6 +662,51 @@ Search workspace users by name, display name, or email. Case-insensitive partial
|
|
|
658
662
|
}
|
|
659
663
|
```
|
|
660
664
|
|
|
665
|
+
---
|
|
666
|
+
|
|
667
|
+
### slack_workflow_save
|
|
668
|
+
|
|
669
|
+
Save or update a workflow profile in file `~/.slack-mcp-workflows.json`. A
|
|
670
|
+
profile binds a `workflow_kind` to channels and people. Only the hosted-only
|
|
671
|
+
tools below read profiles.
|
|
672
|
+
|
|
673
|
+
**Parameters:**
|
|
674
|
+
| Name | Type | Default | Description |
|
|
675
|
+
|------|------|---------|-------------|
|
|
676
|
+
| profile_name | string | *required* | Profile name |
|
|
677
|
+
| workflow_kind | string | *required* | `support_inbox`, `incident_room`, `exec_brief`, `product_launch_watch`, or `custom` |
|
|
678
|
+
| channels | string[] | - | Channel IDs |
|
|
679
|
+
| priority_people | string[] | - | User IDs to weight higher |
|
|
680
|
+
| retention_mode | string | `ephemeral` | `ephemeral` or `persistent` |
|
|
681
|
+
| summary_cadence | string | - | `on_demand`, `daily_8am`, or `weekly_monday` |
|
|
682
|
+
|
|
683
|
+
---
|
|
684
|
+
|
|
685
|
+
### slack_workflows
|
|
686
|
+
|
|
687
|
+
List saved workflow profiles. Optional parameter `workflow_kind` filters them.
|
|
688
|
+
|
|
689
|
+
---
|
|
690
|
+
|
|
691
|
+
### slack_smart_search, slack_catch_me_up, slack_triage
|
|
692
|
+
|
|
693
|
+
Upstream's hosted-only AI tools. This package lists them for parity with
|
|
694
|
+
upstream, but locally each returns error `tool_requires_hosted` without
|
|
695
|
+
calling Slack. The error carries upstream's signup and pricing links.
|
|
696
|
+
|
|
697
|
+
---
|
|
698
|
+
|
|
699
|
+
### mcp_info
|
|
700
|
+
|
|
701
|
+
Report the server version, install source, and whether a newer release
|
|
702
|
+
exists. The stdio server lists it; the HTTP server doesn't. It takes no
|
|
703
|
+
parameters.
|
|
704
|
+
|
|
705
|
+
Each call reads the npm registry. If npm can't be reached, the `update`
|
|
706
|
+
object holds the last cached answer and `update.source` is `cache` instead
|
|
707
|
+
of `live`. `update.pinCommand` is set only when npm has a newer version. See
|
|
708
|
+
the [MCP servers README](../../README.md#version-and-update-notices).
|
|
709
|
+
|
|
661
710
|
## Write Log
|
|
662
711
|
|
|
663
712
|
Each call to `slack_delete_message`, `slack_delete_message_unsafe`,
|
package/docs/DEPLOYMENT-MODES.md
CHANGED
|
@@ -8,15 +8,14 @@ Use this guide to choose the right operating mode before rollout.
|
|
|
8
8
|
- Choose local `web` for browser workflows and manual Slack browsing.
|
|
9
9
|
- Choose hosted HTTP only when you need remote execution and can handle token operations.
|
|
10
10
|
- Choose Smithery/Worker only when your consumers require registry-hosted MCP transport.
|
|
11
|
-
- A managed **Hosted** version is live at [mcp.revasserlabs.com](https://mcp.revasserlabs.com) — Free tier (no card), Pro $19/mo, Team $49/mo flat, Safeguard $199/mo (waitlist). See [pricing](https://mcp.revasserlabs.com/pricing).
|
|
12
11
|
|
|
13
12
|
## Mode Matrix
|
|
14
13
|
|
|
15
14
|
| Mode | Start Command | Best For | Auth Material | Exposure | Notes |
|
|
16
15
|
|------|---------------|----------|---------------|----------|-------|
|
|
17
|
-
| Local MCP (`stdio`) | `bunx @uniquedivine/mcp-slack` | Individual daily usage in Claude | `SLACK_TOKEN` + `SLACK_COOKIE` via token file/env | Local process |
|
|
16
|
+
| Local MCP (`stdio`) | `bunx @uniquedivine/mcp-slack` | Individual daily usage in Claude | `SLACK_TOKEN` + `SLACK_COOKIE` via token file/env | Local process | 26 tools: 25 Slack tools plus `mcp_info`. |
|
|
18
17
|
| Local Web UI (`web`) | `bunx @uniquedivine/mcp-slack web` | Browser-first usage, manual search/send | Same as above + generated API key | `localhost` by default | Useful when MCP is not available |
|
|
19
|
-
| Hosted MCP (`http`) | `bun src/server-http.js` | Controlled hosted integration | Env-injected Slack token/cookie + HTTP bearer token | Remote endpoint | `/mcp`
|
|
18
|
+
| Hosted MCP (`http`) | `bun src/server-http.js` | Controlled hosted integration | Env-injected Slack token/cookie + HTTP bearer token | Remote endpoint | `/mcp` requires a bearer token. The `_unsafe` tools need `SLACK_MCP_ENABLE_UNSAFE_TOOLS=true`. |
|
|
20
19
|
| Smithery/Worker | `wrangler deploy` + Smithery publish flow | Registry distribution for hosted consumers | Query/env token handoff | Remote endpoint | Keep worker version parity with npm release |
|
|
21
20
|
|
|
22
21
|
## Team Deployment Guidance
|
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.2 --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.2 --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.2 --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.2"]
|
|
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.2 --doctor` to confirm diagnostic code, then `bunx @uniquedivine/mcp-slack@4.5.2 --setup` with Slack open in Chrome.
|
|
194
|
-
|
|
195
|
-
### "invalid_auth" Error
|
|
196
|
-
|
|
197
|
-
Tokens have expired. Run `bunx @uniquedivine/mcp-slack@4.5.2 --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).
|