Klavis 仓库 Slack Atlas:Slack MCP Server 配置与使用完全指南
Klavis 仓库 Slack Atlas:Slack MCP Server 配置与使用完全指南
本指南以 mcp_servers/slack_atlas/docs/03-configuration-and-usage.md 为核心,系统讲解 Klavis 仓库内 Slack Atlas(slack-mcp-server)的安装方式、传输协议选择、Docker 部署、命令行参数与全部环境变量,并结合 入口实现 等源码说明每个配置项在底层如何生效。读完本文,你将能够根据自身环境(Claude Desktop、Cursor、Docker、公网 SSE)选出一条最合适的接入路径,并正确配置认证 Token、发消息开关、代理、TLS 与日志级别。
1. 配置前须知:三种认证 Token 的取舍
本 MCP Server 通过 xoxc/xoxd 或 xoxp 两类 Slack 凭据访问工作区,配置环境变量前需要先完成认证。三种 Token 的取舍如下:
| Token | 来源 | 说明 |
|---|---|---|
SLACK_MCP_XOXC_TOKEN(xoxc-...) |
浏览器 localStorage | 从浏览器开发者控制台提取 |
SLACK_MCP_XOXD_TOKEN(xoxd-...) |
浏览器 Cookie d |
与 xoxc 配套使用 |
SLACK_MCP_XOXP_TOKEN(xoxp-...) |
api.slack.com/apps 创建 App | User OAuth Token,更安全,无需浏览器会话提取 |
你只需要二选一:要么提供 xoxp,要么同时提供 xoxc 与 xoxd。完整提取步骤见 01-authentication-setup.md:其中 xoxc 通过在浏览器控制台执行 JSON.parse(localStorage.localConfig_v2).teams[...].token 获取,xoxd 则在 Cookies 面板复制名为 d 的 Cookie 值。若走 xoxp 路线,需在创建 App 后配置 channels:history、channels:read、groups:history、groups:read、im:history、im:read、mpim:history、mpim:read、users:read 等只读 scope,如需发消息再追加 chat:write,如需搜索追加 search:read。
2. 五种安装与接入方式总览
原文档 02-installation.md 列出了四种主流安装路径,加上 SSE 远程接入共五种,可根据使用场景选择:
| 方式 | 适用场景 | 传输协议 |
|---|---|---|
| DXT Extension | Claude Desktop,免手改 JSON | stdio |
| Cursor Installer | Cursor 一键接入 | stdio |
| npx + stdio | 本机 Claude Desktop 快速启动 | stdio |
| npx + SSE(mcp-remote) | 远程/公网部署的 MCP 客户端 | sse |
| Docker | 容器化、docker-compose 编排 | stdio / streamable-http |
说明:仓库入口文件 main.go 表明该服务实际支持
stdio、sse、streamable-http三种 transport,其中streamable-http是 Docker 生产镜像的默认模式(见 Dockerfile),配置时可灵活选择。
3. 使用 DXT 扩展(Claude Desktop 免改配置)
DXT(Claude Desktop Extensions)允许在不直接编辑 claude_desktop_config.json 的情况下安装 MCP Server,适合桌面端用户快速上手。
- 打开 Claude Desktop,进入
Settings菜单; - 点击
Extensions标签页; - 将下载的
.dxt扩展文件拖入窗口并点击 Install; - 填写必填配置字段:
- Authentication method:选择
xoxc/xoxd或xoxp; - 若选择
xoxc/xoxd,填入SLACK_MCP_XOXC_TOKEN和SLACK_MCP_XOXD_TOKEN的值; - 若选择
xoxp,填入SLACK_MCP_XOXP_TOKEN的值; - 可选开启 Add Message Tool,允许向频道发送消息;
- 若使用 Enterprise Slack,可按需修改 User-Agent;
- Authentication method:选择
- 启用 MCP Server。
[!IMPORTANT] 若遇到启动问题,可在 Claude Desktop 中禁用内置 Node,改为使用宿主机的 Node。这是 DXT 的已知问题(相关 issue 见 anthropics/dxt#45),并非本服务自身缺陷。
4. 使用 Cursor 一键安装
Cursor 提供 One-Click MCP 安装方式,官方预置了两套配置:
- npx + xoxc/xoxd 方式:命令为
npx -y slack-mcp-server@latest --transport stdio,环境变量为SLACK_MCP_XOXC_TOKEN与SLACK_MCP_XOXD_TOKEN; - npx + xoxp 方式:命令同上,环境变量为
SLACK_MCP_XOXP_TOKEN。
[!IMPORTANT] 上述预置配置中的 Token 均为示例占位值(如
xoxc-...),安装后务必替换为你自己的 Token。
5. 使用 npx + stdio 直连 Claude Desktop
如果已安装 npm,这是在本机 Claude Desktop 上启动 slack-mcp-server 最快的方式。打开 claude_desktop_config.json,在 mcpServers 列表中新增配置:
方式一:使用 XOXP Token
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"slack-mcp-server@latest",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXP_TOKEN": "xoxp-..."
}
}
}
}
方式二:使用 XOXC/XOXD Token
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"-y",
"slack-mcp-server@latest",
"--transport",
"stdio"
],
"env": {
"SLACK_MCP_XOXC_TOKEN": "xoxc-...",
"SLACK_MCP_XOXD_TOKEN": "xoxd-..."
}
}
}
}
[!WARNING] 若使用 Enterprise Slack,建议将
SLACK_MCP_USER_AGENT设置为提取xoxc/xoxd时所用浏览器的 User-Agent 字符串,并开启SLACK_MCP_CUSTOM_TLS以执行仿真实浏览器的自定义 TLS 握手。在安全策略较高的环境中,这是服务正常工作的必要条件。
5.1 stdio + Docker 变体
如果希望容器化运行,可让 command 指向 docker,但需要将 Token 同时以 -e 参数和 env 字段注入:
XOXP Token 版:
{
"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-..."
}
}
}
}
XOXC/XOXD Token 版:
{
"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-..."
}
}
}
}
更多容器化细节见第 7 节](#7-使用-docker-部署)。注意镜像入口为 mcp-server 命令,--transport stdio 必须显式指定,否则会走镜像默认的 streamable-http 模式(参见 [Dockerfile 的 CMD)。
6. 使用 npx + SSE 远程接入
当需要以 sse 模式远程运行时,Claude Desktop 无法直接与 HTTP 服务通信,需要通过 mcp-remote 包装,并将服务端部署/暴露到可访问的地址(例如 ngrok 或 docker-compose):
{
"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"
}
}
}
}
Windows 用户需要把 command 换成 npx.cmd 的完整路径:
{
"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"
}
}
}
}
这里 SLACK_MCP_SSE_API_KEY 是服务端 SSE 传输的 Bearer Token,在第 8 节环境变量表](#8-环境变量详解)中有定义;它在服务端由 [sse_auth.go 负责校验。
6.1 TLS 与公网暴露
为 SSE 配置 HTTPS 有两个原因:
mcp-remote只能处理https协议;- 对任何暴露到公网的服务,启用 TLS 都是基本安全实践。
可使用 ngrok 快速打通:
ngrok http 3001
随后将 ngrok 返回的 https://xxxx.ngrok-free.app 形式的地址填入 mcp-remote 的参数中(https://x.y.z.q:3001/sse 处)。
7. 使用 Docker 部署
先导出 Token 环境变量,再拉取并运行镜像:
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
注意:-e SLACK_MCP_XOXC_TOKEN(不带等号)会直接引用当前 shell 已导出的同名变量值,与 docker run 的语义一致。
7.1 docker-compose 方式
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 # 编辑 .env 文件,填入第一步获取的 Token
docker-compose up -d
仓库内自带的 docker-compose.yml 展示了生产部署的典型形态:通过 env_file: .env 注入凭据,显式设置 SLACK_MCP_HOST: "0.0.0.0"、SLACK_MCP_PORT: "3001" 并映射 3001:3001 端口,同时用命名卷 users_cache 与 channels_cache 持久化两个缓存文件(/app/mcp-server/.users_cache.json 与 /app/mcp-server/.channels_cache.json),避免容器重启后重复拉取用户/频道元数据。该服务被编排在名为 app-tier 的外部网络中,restart: unless-stopped 保证常驻运行。
生产镜像(Dockerfile)基于 alpine:3.22,默认 SLACK_MCP_PORT=5000 并暴露 5000 端口,CMD 为 mcp-server --transport streamable-http——即以 Streamable HTTP 模式对外提供 /mcp 端点,适合容器内部署场景;仓库同时提供 dev 阶段(含 delve 调试器,便于断点调试)。
8. 命令行参数详解
slack-mcp-server 的命令行参数在 main.go 中通过 Go 标准库 flag 解析:
| 参数 | 是否必填 | 说明 |
|---|---|---|
--transport 或 -t |
是 | 选择 MCP Server 传输方式,可选值:stdio、sse、streamable-http |
两点值得注意的源码行为:
- 源码中该 flag 的默认值即为
stdio,且支持长短两种写法(-t与--transport); - 当传入不合法值(如拼写错误)时,服务会以
logger.Fatal直接退出,并打印允许的取值列表stdio,sse,streamable-http; - transport 还会影响日志输出目标:stdio 模式下日志写入 stderr(避免污染与客户端通信的 stdout),sse/streamable-http 模式下写入 stdout(见 main.go)。
SSE 模式监听地址由 SLACK_MCP_HOST(默认 127.0.0.1)与 SLACK_MCP_PORT(默认 13080)决定,日志会打印 http://<host>:<port>/sse 实际端点(main.go);而 streamable-http 模式的默认 HOST 是 0.0.0.0,端点为 http://<host>:<port>/mcp。
9. 环境变量详解
下表为完整的环境变量清单(与 README.md 保持一致):
| 变量 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
SLACK_MCP_XOXC_TOKEN |
是* | nil |
Slack 浏览器 Token(xoxc-...) |
SLACK_MCP_XOXD_TOKEN |
是* | nil |
Slack 浏览器 Cookie d(xoxd-...) |
SLACK_MCP_XOXP_TOKEN |
是* | nil |
User OAuth Token(xoxp-...),xoxc/xoxd 的替代方案 |
SLACK_MCP_PORT |
否 | 13080 |
MCP Server 监听端口 |
SLACK_MCP_HOST |
否 | 127.0.0.1 |
MCP Server 监听主机 |
SLACK_MCP_SSE_API_KEY |
否 | nil |
SSE 传输的 Bearer Token |
SLACK_MCP_PROXY |
否 | nil |
出站请求的代理 URL |
SLACK_MCP_USER_AGENT |
否 | nil |
自定义 User-Agent(Enterprise Slack 环境) |
SLACK_MCP_CUSTOM_TLS |
否 | nil |
基于 SLACK_MCP_USER_AGENT 或默认 UA 向 Slack 服务器发送自定义 TLS 握手(Enterprise Slack 环境) |
SLACK_MCP_SERVER_CA |
否 | nil |
CA 证书路径 |
SLACK_MCP_SERVER_CA_TOOLKIT |
否 | nil |
将 HTTPToolkit CA 证书注入根信任库,用于 MitM 调试 |
SLACK_MCP_SERVER_CA_INSECURE |
否 | false |
信任所有不安全请求(不推荐) |
SLACK_MCP_ADD_MESSAGE_TOOL |
否 | nil |
启用 conversations_add_message 发消息工具:设为 true 表示全部频道可用;设为逗号分隔的频道 ID 白名单;在频道 ID 前加 ! 表示除列出的频道外全部可用;空值默认禁用发消息 |
SLACK_MCP_ADD_MESSAGE_MARK |
否 | nil |
启用发消息工具后,新发送的消息自动标记为已读 |
SLACK_MCP_ADD_MESSAGE_UNFURLING |
否 | nil |
允许 Slack 展开已发布链接,或设置逗号分隔的域名白名单(如 github.com,slack.com);若文本同时包含白名单与未知域名,出于安全将禁用 unfurl |
SLACK_MCP_USERS_CACHE |
否 | .users_cache.json |
用户缓存文件路径,避免启动时重复调用 API |
SLACK_MCP_CHANNELS_CACHE |
否 | .channels_cache_v2.json |
频道缓存文件路径,避免启动时重复调用 API |
SLACK_MCP_LOG_LEVEL |
否 | info |
日志级别,可选 debug、info、warn、error、panic、fatal |
*你需要 xoxp 或同时提供 xoxc/xoxd 来完成认证。
9.1 环境变量在源码中的落地
对照源码,几个关键配置项的实际行为如下:
SLACK_MCP_ADD_MESSAGE_TOOL的合法性校验:入口在启动时会调用validateToolConfig(main.go)。该校验规则明确:true/1/空值视为合法;按逗号切分后,不允许同时出现白名单频道与!前缀黑名单频道,否则报错cannot mix allowed and disallowed (! prefixed) channels并以logger.Fatal退出。也就是说,白名单与黑名单只能二选一。- 日志级别与格式:
SLACK_MCP_LOG_LEVEL决定 zap 日志级别(非法值回退info);日志输出格式会自动推断——当检测到SLACK_MCP_LOG_FORMAT=json、ENVIRONMENT为production/prod/staging、运行于 Kubernetes/Docker 环境,或 stdout 非 TTY 时,自动切换为 JSON 格式,便于采集(main.go)。 - 缓存文件:
SLACK_MCP_USERS_CACHE与SLACK_MCP_CHANNELS_CACHE对应两个 JSON 缓存文件,缓存用户与频道信息以避免启动阶段重复 API 调用。需要留意的是,README 的限制矩阵明确指出:没有用户缓存与频道缓存时,channels_list工具完全不可用,conversations_*系列工具能力受限(无法用@userHandle/#channel-name检索消息)。因此生产环境务必保证两个缓存文件可写。
10. 配置完成后:验证与调试
接入后可通过仓库 README 提供的两种方式验证:
# 使用 MCP Inspector 以 stdio 方式调试
npx @modelcontextprotocol/inspector go run mcp/mcp-server.go --transport stdio
# 查看 Claude Desktop 侧日志(macOS)
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
可验证的核心工具(均注册于 server.go):
conversations_history:按channel_id拉取频道/DM 消息,limit支持时间范围(如1d、1w、30d)或消息条数(如50),返回的cursor用于翻页;conversations_replies:按channel_id+thread_ts拉取线程;conversations_add_message:发消息(默认禁用,需配置SLACK_MCP_ADD_MESSAGE_TOOL),支持text/markdown与text/plain两种content_type;conversations_search_messages:多条件搜索,支持按频道、用户、日期区间、仅线程等过滤;channels_list:按mpim、im、public_channel、private_channel类型列出频道。
11. 安全注意事项
- 切勿分享 API Token;
xoxc/xoxd属于浏览器会话凭据,等同于你的账号访问权; - 保持
.env文件私密,不要提交到版本库; - 公网部署 SSE 时务必配置
SLACK_MCP_SSE_API_KEY并启用 TLS; SLACK_MCP_SERVER_CA_INSECURE仅用于调试,生产环境应保持关闭(默认false)。