@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 CHANGED
@@ -1,8 +1,11 @@
1
1
  # Slack MCP
2
2
 
3
- Read Slack channels, threads and search results, and perform explicitly
4
- authorized writes through your user session. This server is maintained as
5
- part of Jiyuu. It preserves the imported stdio, HTTP and web entrypoints.
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.2 --setup
15
- bunx @uniquedivine/mcp-slack@4.5.2
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.2
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.2"]
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.2"]
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.2` pin in the client configuration to that version.
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
- ## Install From Source
73
+ ## Tools
70
74
 
71
- Requirements: Git and Bun 1.4.3 or newer. Linked executables, package scripts,
72
- tests and CI use Bun directly; no Node installation or `node` shim is needed.
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
- ```sh
75
- git clone https://github.com/Unique-Divine/jiyuu.git
76
- cd jiyuu
77
- just --justfile mcp/slack/justfile install
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
- Without Just, run `bun install --frozen-lockfile` inside `mcp/slack`.
81
- To make the existing command names available, run `just link` in that directory.
82
- This uses `bun link` and points them at this source checkout. The executable
83
- shebangs launch Bun directly.
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
- Use the setup helper, which stores credentials outside the source tree:
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
- cd mcp/slack
91
- bun src/cli.js --setup
121
+ bunx @uniquedivine/mcp-slack@4.5.3 --setup
92
122
  ```
93
123
 
94
- The server accepts `SLACK_TOKEN` and `SLACK_COOKIE`, or uses the existing
95
- `~/.slack-mcp-tokens.json` store. Existing local token, workflow and cache
96
- locations are retained. No new credentials are needed for a checkout move.
97
- Do not commit tokens, cookies, browser profiles or local exports.
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
- ## Configure an MCP Client From Source
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
- After `just link`, the existing configuration remains valid:
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, use `bun` with the absolute path to `src/cli.js`.
112
- Restart the MCP connection after relinking or changing code. Verify the
113
- connected Slack identity before performing writes.
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 native `bun:test` suite uses `expect`
125
- matchers and covers tool/handler parity, rich
126
- message fields and authentication-error handling without sending Slack messages.
127
- `check` builds the entrypoints to an ignored cache to catch import and syntax
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 remain available through `bun src/cli.js http` and
134
- `bun src/cli.js web`. The inherited hosted-service, pricing and marketing code
135
- has not been removed in this compatibility import. Keeping it is not a
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. The version continues from the imported
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
- ## Origin and License
205
+ ## License
144
206
 
145
- Imported from `Unique-Divine/slack-mcp-server`, originally forked from
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": "james",
18
- "team": "Rêvasser",
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": "james",
74
- "team": "Rêvasser"
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 this tool's **output shape only** — it surfaces fields Slack
153
- already returns on the message object: `attachments`, `blocks`, `files`, `reactions`, `metadata`,
154
- plus `subtype`, `bot_id`, `app_id` (markers that flag automated / bot / app messages) and `team`
155
- (the workspace id, present on all messages). Especially `blocks` can be large, so it's opt-in per
156
- call to keep MCP client context lean.
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 **separate, independent** Slack request flag: its only effect is to add
159
- the full `event_payload` inside a message's developer `metadata` (without it you still get
160
- `metadata.event_type`). The two are orthogonal — set `include_rich_message_fields` to see `metadata`
161
- in the output at all; additionally set `include_all_metadata` for the full payload.
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
- Note: `slack_search_messages` matches are thin — Slack's search API does not return these rich
164
- fields on matches (only `team`). To read rich content for a search hit, call
165
- `slack_conversations_history` or `slack_get_thread` on the match's channel/ts.
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/james/export.json",
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`,
@@ -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 | Lowest ops burden. Free. 21 tools (16 read/write + 2 workflow profile primitives + 3 discoverable upgrade stubs to hosted). |
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` is bearer-protected by default; configure CORS allowlist |
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
- ## Hosted (Coming Soon)
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
- A hosted version with permanent OAuth tokens, semantic search, and AI summaries is in development at [mcp.revasserlabs.com](https://mcp.revasserlabs.com). The current release is self-hosted only — continue below.
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
- ## Self-Hosted Setup
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
- bun add -g @uniquedivine/mcp-slack@4.5.2
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
- ### 1b. Or Clone the Repository
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
- ### 2. Verify Installation
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
- tmpdir="$(mktemp -d)"
37
- cd "$tmpdir"
38
- bunx @uniquedivine/mcp-slack@4.5.2 --version
39
- bunx @uniquedivine/mcp-slack@4.5.2 --help
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
- Expected:
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
- ### 3. Get Slack Tokens
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
- **Option A: Setup Wizard**
50
+ Flag `--status` is read-only and never runs Chrome extraction.
55
51
 
56
- 1. Open Chrome
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
- **Option B: Automatic Extraction (repo clone workflow)**
54
+ Run the setup wizard:
64
55
 
65
56
  ```bash
66
- npm run tokens:auto
57
+ bunx @uniquedivine/mcp-slack@4.5.3 --setup
67
58
  ```
68
59
 
69
- **Option C: Manual Extraction**
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
- ```json
92
- {
93
- "mcpServers": {
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
- Fully restart Claude Desktop (Cmd+Q on macOS, then reopen).
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
- **Verify it's working:** Check `~/Library/Logs/Claude/mcp-server-slack.log` (macOS)
84
+ ## 4. Configure a Client
105
85
 
106
- ### 5. Configure Claude Code (CLI)
86
+ Claude Code:
107
87
 
108
88
  ```bash
109
- claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.2
89
+ claude mcp add slack -- bunx @uniquedivine/mcp-slack@4.5.3
110
90
  ```
111
91
 
112
- Or manually edit `~/.claude.json`:
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.2"]
101
+ "args": ["@uniquedivine/mcp-slack@4.5.3"]
121
102
  }
122
103
  }
123
104
  }
124
105
  ```
125
106
 
126
- Claude Code reads tokens from `~/.slack-mcp-tokens.json` automatically.
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
- ### 6. Restart Claude
111
+ ## 5. Verify the Connection
129
112
 
130
- The Slack tools will now be available in both Claude Desktop and Claude Code.
113
+ Call tool `slack_health_check`. It returns your user and team names.
131
114
 
132
- ## Verification
115
+ ## Keep Tokens Fresh While the Client Is Closed (macOS)
133
116
 
134
- In Claude Code, try:
135
- ```
136
- slack_health_check
137
- ```
138
-
139
- You should see your username and team name.
140
-
141
- ## Keep Tokens Fresh While Claude Is Closed (macOS, Optional)
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
- A LaunchAgent fixes this. It runs token refresh twice a day regardless of whether Claude is open, as long as Chrome is running with a Slack tab somewhere.
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.2 --refresh-tokens</string>
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
- **Why the absolute `bunx` path:** LaunchAgents start without your shell profile, so `bunx` is not on `PATH`. The `bash -c` wrapper expands `$HOME` to the default Bun install path, `~/.bun/bin/bunx`. If you installed Bun with Homebrew, use `/opt/homebrew/bin/bunx` instead. Run `bunx` directly, not through `node`. Command `bunx` is a native Bun binary, not a JavaScript file. Keep the version pin equal to the one in your MCP client config.
186
-
187
- **Trade-off:** Chrome must be running for extraction to succeed. If it's not, the LaunchAgent logs "Failed to extract" and tokens stay where they are — which is fine for another 12 hours.
188
-
189
- ## Troubleshooting
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
- Make sure:
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).