readme improvements

This commit is contained in:
Dmitrii Korotovskii
2025-06-25 21:22:08 +02:00
parent 06182f8ff6
commit 7b6fb20b78
5 changed files with 283 additions and 269 deletions
+13 -268
View File
@@ -1,12 +1,21 @@
# Slack MCP Server
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 😏.
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 😏.
> [!IMPORTANT]
> We need your support! Each month, over 10,000 engineers visit this repository, and more than 2,000 are already using it.
>
> 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.
This feature-rich Slack MCP Server has:
- **Stealth mode**: Run the server without any additional permissions or bot installations.
- **OAuth mode**: Use secure OAuth tokens for secure access without needing to refresh or extract tokens from the browser.
- **Channel and thread support**: Fetch messages from channels and threads, including activity messages.
- **DM and Group DM support**: Retrieve direct messages and group direct messages.
- **Smart History**: Fetch messages with pagination by date (d1, 7d, 1m) or message count.
- **Stdio and SSE transports**: Use the server with any MCP client that supports Stdio or SSE transports.
- **Proxy support**: Configure the server to use a proxy for outgoing requests.
### Feature Demo
![ezgif-316311ee04f444](https://github.com/user-attachments/assets/35dc9895-e695-4e56-acdc-1a46d6520ba0)
@@ -43,273 +52,9 @@ Model Context Protocol (MCP) server for Slack Workspaces. This integration suppo
## Setup Guide
### 1. Authentication Setup
Open up your Slack in your browser and login.
#### Lookup `SLACK_MCP_XOXC_TOKEN`
- Open your browser's Developer Console.
- In Firefox, under `Tools -> Browser Tools -> Web Developer tools` in the menu bar
- In Chrome, click the "three dots" button to the right of the URL Bar, then select
`More Tools -> Developer Tools`
- Switch to the console tab.
- Type "allow pasting" and press ENTER.
- Paste the following snippet and press ENTER to execute:
`JSON.parse(localStorage.localConfig_v2).teams[document.location.pathname.match(/^\/client\/([A-Z0-9]+)/)[1]].token`
Token value is printed right after the executed command (it starts with
`xoxc-`), save it somewhere for now.
#### Lookup `SLACK_MCP_XOXD_TOKEN`
- Switch to "Application" tab and select "Cookies" in the left navigation pane.
- Find the cookie with the name `d`. That's right, just the letter `d`.
- Double-click the Value of this cookie.
- Press Ctrl+C or Cmd+C to copy it's value to clipboard.
- Save it for later.
#### Alternative: Using `SLACK_MCP_XOXP_TOKEN` (User OAuth)
Instead of using browser-based tokens (XOXC/XOXD), you can use a User OAuth token:
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
2. Under "OAuth & Permissions", add the following scopes:
- `channels:history` - View messages in public channels
- `channels:read` - View basic information about public channels
- `groups:history` - View messages in private channels
- `groups:read` - View basic information about private channels
- `im:history` - View messages in direct messages
- `im:read` - View basic information about direct messages
- `mpim:history` - View messages in group direct messages
- `mpim:read` - View basic information about group direct messages
- `users:read` - View people in a workspace
3. Install the app to your workspace
4. Copy the "User OAuth Token" (starts with `xoxp-`)
> **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.
### 2. Installation
Choose one of these installation methods:
- [npx](#Using-npx)
- [Docker](#Using-Docker)
### 3. Configuration and Usage
You can configure the MCP server using command line arguments and environment variables.
#### Using npx
If you have npm installed, this is the fastest way to get started with `slack-mcp-server` on Claude Desktop.
Open your `claude_desktop_config.json` and add the mcp server to the list of `mcpServers`:
**Option 1: Using XOXP Token**
``` json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"slack-mcp-server@latest",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
**Option 2: Using XOXC/XOXD Tokens**
``` json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"slack-mcp-server@latest",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
}
}
}
}
```
<details>
<summary>Or, stdio transport with docker.</summary>
**Option 1: Using XOXP Token**
```json
{
"mcpServers": {
"slack": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SLACK_MCP_XOXP_TOKEN",
"ghcr.io/korotovsky/slack-mcp-server",
"mcp-server",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
**Option 2: Using XOXC/XOXD Tokens**
```json
{
"mcpServers": {
"slack": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SLACK_MCP_XOXC_TOKEN",
"-e",
"SLACK_MCP_XOXD_TOKEN",
"ghcr.io/korotovsky/slack-mcp-server",
"mcp-server",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
}
}
}
}
```
Please see [Docker](#Using-Docker) for more information.
</details>
#### Using npx with `sse` transport:
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`.
```json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://x.y.z.q:3001/sse",
"--header",
"Authorization: Bearer ${SLACK_MCP_SSE_API_KEY}"
],
"env": {
"SLACK_MCP_SSE_API_KEY": "my-$$e-$ecret"
}
}
}
}
```
<details>
<summary>Or, sse transport for Windows.</summary>
```json
{
"mcpServers": {
"slack": {
"command": "C:\\Progra~1\\nodejs\\npx.cmd",
"args": [
"-y",
"mcp-remote",
"https://x.y.z.q:3001/sse",
"--header",
"Authorization: Bearer ${SLACK_MCP_SSE_API_KEY}"
],
"env": {
"SLACK_MCP_SSE_API_KEY": "my-$$e-$ecret"
}
}
}
}
```
</details>
#### TLS and Exposing to the Internet
There are several reasons why you might need to setup HTTPS for your SSE.
- `mcp-remote` is capable to handle only https schemes;
- it is generally a good practice to use TLS for any service exposed to the internet;
You could use `ngrok`:
```bash
ngrok http 3001
```
and then use the endpoint `https://903d-xxx-xxxx-xxxx-10b4.ngrok-free.app` for your `mcp-remote` argument.
#### Using Docker
For detailed information about all environment variables, see [Environment Variables](https://github.com/korotovsky/slack-mcp-server?tab=readme-ov-file#environment-variables).
```bash
export SLACK_MCP_XOXC_TOKEN=xoxc-...
export SLACK_MCP_XOXD_TOKEN=xoxd-...
docker pull ghcr.io/korotovsky/slack-mcp-server:latest
docker run -i --rm \
-e SLACK_MCP_XOXC_TOKEN \
-e SLACK_MCP_XOXD_TOKEN \
slack-mcp-server mcp-server --transport stdio
```
Or, the docker-compose way:
```bash
wget -O docker-compose.yml https://github.com/korotovsky/slack-mcp-server/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/korotovsky/slack-mcp-server/releases/latest/download/default.env.dist
nano .env # Edit .env file with your tokens from step 1 of the setup guide
docker-compose up -d
```
#### Console Arguments
| Argument | Required ? | Description |
|-----------------------|------------|--------------------------------------------------------------------------|
| `--transport` or `-t` | Yes | Select transport for the MCP Server, possible values are: `stdio`, `sse` |
#### Environment Variables
| Variable | Required ? | Default | Description |
|--------------------------------|------------|-------------|-------------------------------------------------------------------------------|
| `SLACK_MCP_XOXC_TOKEN` | Yes | `nil` | Authentication data token field `token` from POST data field-set (`xoxc-...`) |
| `SLACK_MCP_XOXD_TOKEN` | Yes | `nil` | Authentication data token from cookie `d` (`xoxd-...`) |
| `SLACK_MCP_SERVER_PORT` | No | `3001` | Port for the MCP server to listen on |
| `SLACK_MCP_SERVER_HOST` | No | `127.0.0.1` | Host for the MCP server to listen on |
| `SLACK_MCP_SSE_API_KEY` | No | `nil` | Authorization Bearer token when `transport` is `sse` |
| `SLACK_MCP_PROXY` | No | `nil` | Proxy URL for the MCP server to use |
| `SLACK_MCP_SERVER_CA` | No | `nil` | Path to the CA certificate of the trust store |
| `SLACK_MCP_SERVER_CA_INSECURE` | No | `false` | Trust all insecure requests (NOT RECOMMENDED) |
- [Authentication Setup](docs/01-authentication-setup.md)
- [Installation](docs/02-installation.md)
- [Configuration and Usage](docs/03-configuration-and-usage.md)
### Debugging Tools
+47
View File
@@ -0,0 +1,47 @@
### 1. Authentication Setup
Open up your Slack in your browser and login.
#### Lookup `SLACK_MCP_XOXC_TOKEN`
- Open your browser's Developer Console.
- In Firefox, under `Tools -> Browser Tools -> Web Developer tools` in the menu bar
- In Chrome, click the "three dots" button to the right of the URL Bar, then select
`More Tools -> Developer Tools`
- Switch to the console tab.
- Type "allow pasting" and press ENTER.
- Paste the following snippet and press ENTER to execute:
`JSON.parse(localStorage.localConfig_v2).teams[document.location.pathname.match(/^\/client\/([A-Z0-9]+)/)[1]].token`
Token value is printed right after the executed command (it starts with
`xoxc-`), save it somewhere for now.
#### Lookup `SLACK_MCP_XOXD_TOKEN`
- Switch to "Application" tab and select "Cookies" in the left navigation pane.
- Find the cookie with the name `d`. That's right, just the letter `d`.
- Double-click the Value of this cookie.
- Press Ctrl+C or Cmd+C to copy it's value to clipboard.
- Save it for later.
#### Alternative: Using `SLACK_MCP_XOXP_TOKEN` (User OAuth)
Instead of using browser-based tokens (`xoxc`/`xoxd`), you can use a User OAuth token:
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
2. Under "OAuth & Permissions", add the following scopes:
- `channels:history` - View messages in public channels
- `channels:read` - View basic information about public channels
- `groups:history` - View messages in private channels
- `groups:read` - View basic information about private channels
- `im:history` - View messages in direct messages
- `im:read` - View basic information about direct messages
- `mpim:history` - View messages in group direct messages
- `mpim:read` - View basic information about group direct messages
- `users:read` - View people in a workspace
3. Install the app to your workspace
4. Copy the "User OAuth Token" (starts with `xoxp-`)
> **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.
See next: [Installation](02-installation.md)
+8
View File
@@ -0,0 +1,8 @@
### 2. Installation
Choose one of these installation methods:
- [npx](03-configuration-and-usage.md#Using-npx)
- [Docker](03-configuration-and-usage.md#Using-Docker)
See next: [Configuration and Usage](03-configuration-and-usage.md)
+214
View File
@@ -0,0 +1,214 @@
### 3. Configuration and Usage
You can configure the MCP server using command line arguments and environment variables.
#### Using npx
If you have npm installed, this is the fastest way to get started with `slack-mcp-server` on Claude Desktop.
Open your `claude_desktop_config.json` and add the mcp server to the list of `mcpServers`:
**Option 1: Using XOXP Token**
``` json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"slack-mcp-server@latest",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
**Option 2: Using XOXC/XOXD Tokens**
``` json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"slack-mcp-server@latest",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
}
}
}
}
```
<details>
<summary>Or, stdio transport with docker.</summary>
**Option 1: Using XOXP Token**
```json
{
"mcpServers": {
"slack": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SLACK_MCP_XOXP_TOKEN",
"ghcr.io/korotovsky/slack-mcp-server",
"mcp-server",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
}
}
}
}
```
**Option 2: Using XOXC/XOXD Tokens**
```json
{
"mcpServers": {
"slack": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"SLACK_MCP_XOXC_TOKEN",
"-e",
"SLACK_MCP_XOXD_TOKEN",
"ghcr.io/korotovsky/slack-mcp-server",
"mcp-server",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
}
}
}
}
```
Please see [Docker](#Using-Docker) for more information.
</details>
#### Using npx with `sse` transport:
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`.
```json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://x.y.z.q:3001/sse",
"--header",
"Authorization: Bearer ${SLACK_MCP_SSE_API_KEY}"
],
"env": {
"SLACK_MCP_SSE_API_KEY": "my-$$e-$ecret"
}
}
}
}
```
<details>
<summary>Or, sse transport for Windows.</summary>
```json
{
"mcpServers": {
"slack": {
"command": "C:\\Progra~1\\nodejs\\npx.cmd",
"args": [
"-y",
"mcp-remote",
"https://x.y.z.q:3001/sse",
"--header",
"Authorization: Bearer ${SLACK_MCP_SSE_API_KEY}"
],
"env": {
"SLACK_MCP_SSE_API_KEY": "my-$$e-$ecret"
}
}
}
}
```
</details>
#### TLS and Exposing to the Internet
There are several reasons why you might need to setup HTTPS for your SSE.
- `mcp-remote` is capable to handle only https schemes;
- it is generally a good practice to use TLS for any service exposed to the internet;
You could use `ngrok`:
```bash
ngrok http 3001
```
and then use the endpoint `https://903d-xxx-xxxx-xxxx-10b4.ngrok-free.app` for your `mcp-remote` argument.
#### Using Docker
For detailed information about all environment variables, see [Environment Variables](https://github.com/korotovsky/slack-mcp-server?tab=readme-ov-file#environment-variables).
```bash
export SLACK_MCP_XOXC_TOKEN=xoxc-...
export SLACK_MCP_XOXD_TOKEN=xoxd-...
docker pull ghcr.io/korotovsky/slack-mcp-server:latest
docker run -i --rm \
-e SLACK_MCP_XOXC_TOKEN \
-e SLACK_MCP_XOXD_TOKEN \
slack-mcp-server mcp-server --transport stdio
```
Or, the docker-compose way:
```bash
wget -O docker-compose.yml https://github.com/korotovsky/slack-mcp-server/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/korotovsky/slack-mcp-server/releases/latest/download/default.env.dist
nano .env # Edit .env file with your tokens from step 1 of the setup guide
docker-compose up -d
```
#### Console Arguments
| Argument | Required ? | Description |
|-----------------------|------------|--------------------------------------------------------------------------|
| `--transport` or `-t` | Yes | Select transport for the MCP Server, possible values are: `stdio`, `sse` |
#### Environment Variables
| Variable | Required ? | Default | Description |
|--------------------------------|------------|-------------|-------------------------------------------------------------------------------|
| `SLACK_MCP_XOXC_TOKEN` | Yes | `nil` | Authentication data token field `token` from POST data field-set (`xoxc-...`) |
| `SLACK_MCP_XOXD_TOKEN` | Yes | `nil` | Authentication data token from cookie `d` (`xoxd-...`) |
| `SLACK_MCP_SERVER_PORT` | No | `3001` | Port for the MCP server to listen on |
| `SLACK_MCP_SERVER_HOST` | No | `127.0.0.1` | Host for the MCP server to listen on |
| `SLACK_MCP_SSE_API_KEY` | No | `nil` | Authorization Bearer token when `transport` is `sse` |
| `SLACK_MCP_PROXY` | No | `nil` | Proxy URL for the MCP server to use |
| `SLACK_MCP_SERVER_CA` | No | `nil` | Path to the CA certificate of the trust store |
| `SLACK_MCP_SERVER_CA_INSECURE` | No | `false` | Trust all insecure requests (NOT RECOMMENDED) |
+1 -1
View File
@@ -16,7 +16,7 @@ type MCPServer struct {
func NewMCPServer(provider *provider.ApiProvider) *MCPServer {
s := server.NewMCPServer(
"Slack MCP Server",
"1.1.12",
"1.1.15",
server.WithLogging(),
server.WithRecovery(),
)