Skip to content

Commit 44b645d

Browse files
korotovskykorotovsky
authored
Merge pull request #26 from korotovsky/split-and-improve-readme
readme improvements
2 parents 06182f8 + b225a0e commit 44b645d

File tree

5 files changed

+286
-269
lines changed

5 files changed

+286
-269
lines changed

‎README.md‎

Lines changed: 16 additions & 268 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,24 @@
11
# Slack MCP Server
22

3-
Model Context Protocol (MCP) server for Slack Workspaces. This integration supports both Stdio and SSE transports, proxy settings and does not require any permissions or bots being created or approved by Workspace admins 😏.
3+
Model Context Protocol (MCP) server for Slack Workspaces. The most powerful MCP Slack server — supports Stdio and SSE transports, proxy settings, DMs, Group DMs, Smart History fetch (by date or count), may work via OAuth or in complete stealth mode with no permissions and scopes in Workspace 😏.
44

55
> [!IMPORTANT]
66
> We need your support! Each month, over 10,000 engineers visit this repository, and more than 2,000 are already using it.
77
>
88
> If you appreciate the work our [contributors](https://github.com/korotovsky/slack-mcp-server/graphs/contributors) have put into this project, please consider giving the repository a star.
99
10+
This feature-rich Slack MCP Server has:
11+
- **Stealth mode**: Run the server without any additional permissions or bot installations.
12+
- **OAuth mode**: Use secure OAuth tokens for secure access without needing to refresh or extract tokens from the browser.
13+
- **Channel and thread support**: Fetch messages from channels and threads, including activity messages.
14+
- **Channel by name**: Fetch channels by their names, such as `#general`, not only but their ids.
15+
- **DM and Group DM support**: Retrieve direct messages and group direct messages.
16+
- **Embedded user information**: Embed user information in messages, for better context.
17+
- **Smart History**: Fetch messages with pagination by date (d1, 7d, 1m) or message count.
18+
- **Cache support**: Cache users and channels for faster access.
19+
- **Stdio and SSE transports**: Use the server with any MCP client that supports Stdio or SSE transports.
20+
- **Proxy support**: Configure the server to use a proxy for outgoing requests.
21+
1022
### Feature Demo
1123

1224
![ezgif-316311ee04f444](https://github.com/user-attachments/assets/35dc9895-e695-4e56-acdc-1a46d6520ba0)
@@ -43,273 +55,9 @@ Model Context Protocol (MCP) server for Slack Workspaces. This integration suppo
4355

4456
## Setup Guide
4557

46-
### 1. Authentication Setup
47-
48-
Open up your Slack in your browser and login.
49-
50-
#### Lookup `SLACK_MCP_XOXC_TOKEN`
51-
52-
- Open your browser's Developer Console.
53-
- In Firefox, under `Tools -> Browser Tools -> Web Developer tools` in the menu bar
54-
- In Chrome, click the "three dots" button to the right of the URL Bar, then select
55-
`More Tools -> Developer Tools`
56-
- Switch to the console tab.
57-
- Type "allow pasting" and press ENTER.
58-
- Paste the following snippet and press ENTER to execute:
59-
`JSON.parse(localStorage.localConfig_v2).teams[document.location.pathname.match(/^\/client\/([A-Z0-9]+)/)[1]].token`
60-
61-
Token value is printed right after the executed command (it starts with
62-
`xoxc-`), save it somewhere for now.
63-
64-
#### Lookup `SLACK_MCP_XOXD_TOKEN`
65-
66-
- Switch to "Application" tab and select "Cookies" in the left navigation pane.
67-
- Find the cookie with the name `d`. That's right, just the letter `d`.
68-
- Double-click the Value of this cookie.
69-
- Press Ctrl+C or Cmd+C to copy it's value to clipboard.
70-
- Save it for later.
71-
72-
#### Alternative: Using `SLACK_MCP_XOXP_TOKEN` (User OAuth)
73-
74-
Instead of using browser-based tokens (XOXC/XOXD), you can use a User OAuth token:
75-
76-
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
77-
2. Under "OAuth & Permissions", add the following scopes:
78-
- `channels:history` - View messages in public channels
79-
- `channels:read` - View basic information about public channels
80-
- `groups:history` - View messages in private channels
81-
- `groups:read` - View basic information about private channels
82-
- `im:history` - View messages in direct messages
83-
- `im:read` - View basic information about direct messages
84-
- `mpim:history` - View messages in group direct messages
85-
- `mpim:read` - View basic information about group direct messages
86-
- `users:read` - View people in a workspace
87-
3. Install the app to your workspace
88-
4. Copy the "User OAuth Token" (starts with `xoxp-`)
89-
90-
> **Note**: You only need **either** XOXP token **or** both XOXC/XOXD tokens. XOXP user tokens are more secure and don't require browser session extraction.
91-
92-
### 2. Installation
93-
94-
Choose one of these installation methods:
95-
96-
- [npx](#Using-npx)
97-
- [Docker](#Using-Docker)
98-
99-
### 3. Configuration and Usage
100-
101-
You can configure the MCP server using command line arguments and environment variables.
102-
103-
#### Using npx
104-
105-
If you have npm installed, this is the fastest way to get started with `slack-mcp-server` on Claude Desktop.
106-
107-
Open your `claude_desktop_config.json` and add the mcp server to the list of `mcpServers`:
108-
109-
**Option 1: Using XOXP Token**
110-
``` json
111-
{
112-
"mcpServers": {
113-
"slack": {
114-
"command": "npx",
115-
"args": [
116-
"-y",
117-
"slack-mcp-server@latest",
118-
"--transport",
119-
"stdio"
120-
],
121-
"env": {
122-
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
123-
}
124-
}
125-
}
126-
}
127-
```
128-
129-
**Option 2: Using XOXC/XOXD Tokens**
130-
``` json
131-
{
132-
"mcpServers": {
133-
"slack": {
134-
"command": "npx",
135-
"args": [
136-
"-y",
137-
"slack-mcp-server@latest",
138-
"--transport",
139-
"stdio"
140-
],
141-
"env": {
142-
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
143-
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
144-
}
145-
}
146-
}
147-
}
148-
```
149-
150-
<details>
151-
<summary>Or, stdio transport with docker.</summary>
152-
153-
**Option 1: Using XOXP Token**
154-
```json
155-
{
156-
"mcpServers": {
157-
"slack": {
158-
"command": "docker",
159-
"args": [
160-
"run",
161-
"-i",
162-
"--rm",
163-
"-e",
164-
"SLACK_MCP_XOXP_TOKEN",
165-
"ghcr.io/korotovsky/slack-mcp-server",
166-
"mcp-server",
167-
"--transport",
168-
"stdio"
169-
],
170-
"env": {
171-
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
172-
}
173-
}
174-
}
175-
}
176-
```
177-
178-
**Option 2: Using XOXC/XOXD Tokens**
179-
```json
180-
{
181-
"mcpServers": {
182-
"slack": {
183-
"command": "docker",
184-
"args": [
185-
"run",
186-
"-i",
187-
"--rm",
188-
"-e",
189-
"SLACK_MCP_XOXC_TOKEN",
190-
"-e",
191-
"SLACK_MCP_XOXD_TOKEN",
192-
"ghcr.io/korotovsky/slack-mcp-server",
193-
"mcp-server",
194-
"--transport",
195-
"stdio"
196-
],
197-
"env": {
198-
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
199-
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
200-
}
201-
}
202-
}
203-
}
204-
```
205-
206-
Please see [Docker](#Using-Docker) for more information.
207-
</details>
208-
209-
#### Using npx with `sse` transport:
210-
211-
In case you would like to run it in `sse` mode, then you should use `mcp-remote` wrapper for Claude Desktop and deploy/expose MCP server somewhere e.g. with `ngrok` or `docker-compose`.
212-
213-
```json
214-
{
215-
"mcpServers": {
216-
"slack": {
217-
"command": "npx",
218-
"args": [
219-
"-y",
220-
"mcp-remote",
221-
"https://x.y.z.q:3001/sse",
222-
"--header",
223-
"Authorization: Bearer ${SLACK_MCP_SSE_API_KEY}"
224-
],
225-
"env": {
226-
"SLACK_MCP_SSE_API_KEY": "my-$$e-$ecret"
227-
}
228-
}
229-
}
230-
}
231-
```
232-
233-
<details>
234-
<summary>Or, sse transport for Windows.</summary>
235-
236-
```json
237-
{
238-
"mcpServers": {
239-
"slack": {
240-
"command": "C:\\Progra~1\\nodejs\\npx.cmd",
241-
"args": [
242-
"-y",
243-
"mcp-remote",
244-
"https://x.y.z.q:3001/sse",
245-
"--header",
246-
"Authorization: Bearer ${SLACK_MCP_SSE_API_KEY}"
247-
],
248-
"env": {
249-
"SLACK_MCP_SSE_API_KEY": "my-$$e-$ecret"
250-
}
251-
}
252-
}
253-
}
254-
```
255-
</details>
256-
257-
#### TLS and Exposing to the Internet
258-
259-
There are several reasons why you might need to setup HTTPS for your SSE.
260-
- `mcp-remote` is capable to handle only https schemes;
261-
- it is generally a good practice to use TLS for any service exposed to the internet;
262-
263-
You could use `ngrok`:
264-
265-
```bash
266-
ngrok http 3001
267-
```
268-
269-
and then use the endpoint `https://903d-xxx-xxxx-xxxx-10b4.ngrok-free.app` for your `mcp-remote` argument.
270-
271-
#### Using Docker
272-
273-
For detailed information about all environment variables, see [Environment Variables](https://github.com/korotovsky/slack-mcp-server?tab=readme-ov-file#environment-variables).
274-
275-
```bash
276-
export SLACK_MCP_XOXC_TOKEN=xoxc-...
277-
export SLACK_MCP_XOXD_TOKEN=xoxd-...
278-
279-
docker pull ghcr.io/korotovsky/slack-mcp-server:latest
280-
docker run -i --rm \
281-
-e SLACK_MCP_XOXC_TOKEN \
282-
-e SLACK_MCP_XOXD_TOKEN \
283-
slack-mcp-server mcp-server --transport stdio
284-
```
285-
286-
Or, the docker-compose way:
287-
288-
```bash
289-
wget -O docker-compose.yml https://github.com/korotovsky/slack-mcp-server/releases/latest/download/docker-compose.yml
290-
wget -O .env https://github.com/korotovsky/slack-mcp-server/releases/latest/download/default.env.dist
291-
nano .env # Edit .env file with your tokens from step 1 of the setup guide
292-
docker-compose up -d
293-
```
294-
295-
#### Console Arguments
296-
297-
| Argument | Required ? | Description |
298-
|-----------------------|------------|--------------------------------------------------------------------------|
299-
| `--transport` or `-t` | Yes | Select transport for the MCP Server, possible values are: `stdio`, `sse` |
300-
301-
#### Environment Variables
302-
303-
| Variable | Required ? | Default | Description |
304-
|--------------------------------|------------|-------------|-------------------------------------------------------------------------------|
305-
| `SLACK_MCP_XOXC_TOKEN` | Yes | `nil` | Authentication data token field `token` from POST data field-set (`xoxc-...`) |
306-
| `SLACK_MCP_XOXD_TOKEN` | Yes | `nil` | Authentication data token from cookie `d` (`xoxd-...`) |
307-
| `SLACK_MCP_SERVER_PORT` | No | `3001` | Port for the MCP server to listen on |
308-
| `SLACK_MCP_SERVER_HOST` | No | `127.0.0.1` | Host for the MCP server to listen on |
309-
| `SLACK_MCP_SSE_API_KEY` | No | `nil` | Authorization Bearer token when `transport` is `sse` |
310-
| `SLACK_MCP_PROXY` | No | `nil` | Proxy URL for the MCP server to use |
311-
| `SLACK_MCP_SERVER_CA` | No | `nil` | Path to the CA certificate of the trust store |
312-
| `SLACK_MCP_SERVER_CA_INSECURE` | No | `false` | Trust all insecure requests (NOT RECOMMENDED) |
58+
- [Authentication Setup](docs/01-authentication-setup.md)
59+
- [Installation](docs/02-installation.md)
60+
- [Configuration and Usage](docs/03-configuration-and-usage.md)
31361

31462
### Debugging Tools
31563

‎docs/01-authentication-setup.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
### 1. Authentication Setup
2+
3+
Open up your Slack in your browser and login.
4+
5+
#### Lookup `SLACK_MCP_XOXC_TOKEN`
6+
7+
- Open your browser's Developer Console.
8+
- In Firefox, under `Tools -> Browser Tools -> Web Developer tools` in the menu bar
9+
- In Chrome, click the "three dots" button to the right of the URL Bar, then select
10+
`More Tools -> Developer Tools`
11+
- Switch to the console tab.
12+
- Type "allow pasting" and press ENTER.
13+
- Paste the following snippet and press ENTER to execute:
14+
`JSON.parse(localStorage.localConfig_v2).teams[document.location.pathname.match(/^\/client\/([A-Z0-9]+)/)[1]].token`
15+
16+
Token value is printed right after the executed command (it starts with
17+
`xoxc-`), save it somewhere for now.
18+
19+
#### Lookup `SLACK_MCP_XOXD_TOKEN`
20+
21+
- Switch to "Application" tab and select "Cookies" in the left navigation pane.
22+
- Find the cookie with the name `d`. That's right, just the letter `d`.
23+
- Double-click the Value of this cookie.
24+
- Press Ctrl+C or Cmd+C to copy it's value to clipboard.
25+
- Save it for later.
26+
27+
#### Alternative: Using `SLACK_MCP_XOXP_TOKEN` (User OAuth)
28+
29+
Instead of using browser-based tokens (`xoxc`/`xoxd`), you can use a User OAuth token:
30+
31+
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
32+
2. Under "OAuth & Permissions", add the following scopes:
33+
- `channels:history` - View messages in public channels
34+
- `channels:read` - View basic information about public channels
35+
- `groups:history` - View messages in private channels
36+
- `groups:read` - View basic information about private channels
37+
- `im:history` - View messages in direct messages
38+
- `im:read` - View basic information about direct messages
39+
- `mpim:history` - View messages in group direct messages
40+
- `mpim:read` - View basic information about group direct messages
41+
- `users:read` - View people in a workspace
42+
3. Install the app to your workspace
43+
4. Copy the "User OAuth Token" (starts with `xoxp-`)
44+
45+
> **Note**: You only need **either** XOXP token **or** both XOXC/XOXD tokens. XOXP user tokens are more secure and don't require browser session extraction.
46+
47+
See next: [Installation](02-installation.md)

‎docs/02-installation.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
### 2. Installation
2+
3+
Choose one of these installation methods:
4+
5+
- [npx](03-configuration-and-usage.md#Using-npx)
6+
- [Docker](03-configuration-and-usage.md#Using-Docker)
7+
8+
See next: [Configuration and Usage](03-configuration-and-usage.md)

0 commit comments

Comments
 (0)