Klavis 仓库 Slack Atlas:Slack MCP Server 配置与使用完全指南

原创2026-09-17 21:51:581,913 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端本地部署认证鉴权API网关

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,适合桌面端用户快速上手。

  1. 打开 Claude Desktop,进入 Settings 菜单;
  2. 点击 Extensions 标签页;
  3. 将下载的 .dxt 扩展文件拖入窗口并点击 Install;
  4. 填写必填配置字段:
    • 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;
  5. 启用 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)。
登录后查看全文
klavis