Klavis 仓库 Slack MCP Server 实战指南:Stealth/OAuth 双模式、Smart History 与安全发信配置

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

Klavis 仓库 Slack MCP Server 实战指南:Stealth/OAuth 双模式、Smart History 与安全发信配置

导读

本文完整解析 Klavis 仓库中 slack_atlas 目录下的 Slack MCP Server(Model Context Protocol 服务器):它让你可以把 Slack 工作区的频道、私信、群组私信、线程与历史消息以标准 MCP 工具/资源的形式暴露给 Claude、Cursor 等任意 MCP 客户端。读完本文,你将掌握两种认证方式(浏览器 xoxc/xoxd 令牌与 xoxp 用户 OAuth 令牌)、四种安装途径(DXT 扩展、Cursor 一键安装、npx、Docker)、五个内置工具的完整参数语义、slack:// 目录资源的用法,以及环境变量与缓存机制对功能边界的实际影响,并能据此搭建一套可安全发消息、可按日期/条数翻页拉取历史的 Slack 智能体工作流。

一、项目定位与核心特性

Slack MCP Server 是一个基于 Go 实现的 MCP 服务器,面向 Slack 工作区提供标准化的读写与检索能力。根据 README 与 入口程序 的说明,其核心特性包括:

  • Stealth(隐身)与 OAuth 两种模式:可以不安装任何 Slack 应用、不申请额外权限和 scope(stealth 模式,直接使用浏览器会话令牌),也可以使用更安全的 xoxp- 用户 OAuth 令牌,无需从浏览器反复提取或刷新令牌。
  • Enterprise Workspaces 支持:通过自定义 User-Agent 与定制 TLS 握手,适配安全策略更高的企业 Slack 环境。
  • 频道/线程/私信全支持:既可用频道 ID(Cxxxxxxxxxx),也可用 #general 这类名称或 @username 这类 DM 别名定位会话。
  • Smart History(智能历史拉取):limit 参数既支持按时间范围(1d、7d、30d、90d)翻页,也支持按消息条数(如 50)翻页。
  • 安全优先的消息发送:conversations_add_message 默认关闭,需要显式通过环境变量开启,并支持频道白名单/黑名单。
  • 内嵌用户信息与缓存:消息中嵌入用户信息以增强 LLM 上下文;用户与频道缓存避免每次启动重复调用 Slack API。
  • Stdio / SSE / Streamable HTTP 传输与代理支持:可对接绝大多数 MCP 客户端,并通过 SLACK_MCP_PROXY 配置出站代理。

从源码结构看,本项目采用典型的分层设计:cmd/slack-mcp-server/main.go 负责参数解析与传输分发,pkg/server/server.go 负责工具/资源注册与 HTTP 服务装配,pkg/handler 实现具体业务逻辑,pkg/provider 封装 Slack API 客户端与缓存。

二、整体架构与源码级调用链

2.1 启动流程

入口 main.go 的执行顺序是:

  1. 通过 -t / --transport 解析传输类型(stdio、sse、streamable-http,默认 stdio)。
  2. 调用 validateToolConfig 校验 SLACK_MCP_ADD_MESSAGE_TOOL 配置合法性。
  3. 构建 ApiProvider(Slack API 提供者)与 MCPServer。
  4. 按传输类型分发:ServeStdio()、ServeSSE() 或 ServeStreamableHTTP()。

值得注意的细节是:sse 模式默认监听 127.0.0.1:13080,而 streamable-http 模式下主机默认是 0.0.0.0(见 main.go),两者都可通过 SLACK_MCP_HOST / SLACK_MCP_PORT 覆盖。

2.2 工具与资源注册

在 server.go 中,服务注册了 5 个工具与 2 个资源:

类型 名称 说明
工具 conversations_history 拉取频道/DM 历史消息
工具 conversations_replies 拉取某条消息所在线程的全部回复
工具 conversations_add_message 向频道/DM/线程发送消息(默认禁用)
工具 conversations_search_messages 多维度过滤检索消息
工具 channels_list 列出频道(支持按成员数排序)
资源 slack://<workspace>/channels 频道 CSV 目录
资源 slack://<workspace>/users 用户 CSV 目录

所有工具定义均基于 mark3labs/mcp-go 框架,参数类型、默认值与描述都声明在注册代码中,与 README 文档一一对应。

2.3 认证与令牌注入

服务内置了统一认证中间件(auth.BuildMiddleware)。对于 HTTP 传输(SSE / Streamable HTTP),令牌通过 x-auth-data 请求头(Base64 编码的 JSON,内含 xoxp_token 或 access_token 字段)或 AUTH_DATA 环境变量注入请求上下文(见 server.go);对于 stdio 传输,则回退读取 SLACK_MCP_XOXP_TOKEN 环境变量(见 api.go)。

2.4 输出格式:CSV 流式返回

历史、回复与搜索结果都以 CSV 形式返回(通过 gocsv 序列化,见 conversations.go),每条消息包含 userID、userUser、realName、channelID、ThreadTs、text、time、cursor 字段。分页游标就放在响应最后一行/最后一列的 cursor 字段中——这正是 README 反复强调"用响应中最后一行/列的值作为下一次请求的 cursor"的原因(实现见 conversations.go)。

三、两种认证方式详解

认证是使用本服务器的第一步。根据 01-authentication-setup.md,你有两种互斥的选择(只需要 xoxp 一种,或者 xoxc/xoxd 两种)。

3.1 方式一:浏览器令牌(Stealth 模式)——xoxc + xoxd

不需要安装任何 Slack 应用,直接从浏览器会话中提取两个值:

提取 SLACK_MCP_XOXC_TOKEN(xoxc- 开头):

  1. 用浏览器登录 Slack 工作区。
  2. 打开开发者控制台:Chrome 中点击地址栏右侧"三个点"→ 更多工具 → 开发者工具;Firefox 中通过菜单 工具 → 浏览器工具 → Web 开发者工具。
  3. 切到 Console 标签页,先输入 allow pasting 回车(允许粘贴),再粘贴执行:
    JSON.parse(localStorage.localConfig_v2).teams[document.location.pathname.match(/^\/client\/([A-Z0-9]+)/)[1]].token
    
  4. 输出值以 xoxc- 开头,保存备用。

提取 SLACK_MCP_XOXD_TOKEN(xoxd- 开头):

  1. 切到 Application 标签页,左侧导航选择 Cookies。
  2. 找到名为 d 的 Cookie(没错,就一个字母 d)。
  3. 双击其 Value,复制到剪贴板保存。

该模式下服务器以"隐身"方式工作——不申请权限、不安装 bot,整个工作区对服务端无感知。

3.2 方式二:用户 OAuth 令牌(推荐)——xoxp

更安全、无需浏览器会话提取。前往 Slack 应用管理页面创建一个新应用,在 OAuth & Permissions 中添加以下 scope,安装到工作区后复制 User OAuth Token(xoxp- 开头):

Scope 用途
channels:history / channels:read 查看公开频道消息与基本信息
groups:history / groups:read 查看私密频道消息与基本信息
im:history / im:read / im:write 查看/发起单聊私信
mpim:history / mpim:read / mpim:write 查看/发起群组私信
users:read 查看工作区成员
chat:write 代表用户发送消息
search:read 搜索工作区内容

其中 im:write、mpim:write、chat:write、search:read 是较新版本才支持的能力(文档标注为 v1.1.18 起新增)。注意:XOXP 令牌与 XOXC/XOXD 只需二选一,不要同时配置以免混淆。

四、安装与四种接入方式

根据 02-installation.md 与 03-configuration-and-usage.md,可按场景选择以下任一方式。

4.1 方式一:DXT 扩展(Claude Desktop 图形化安装)

  1. 下载 DXT 扩展文件(.dxt)。
  2. 打开 Claude Desktop → Settings → Extensions 标签页。
  3. 拖入 .dxt 文件并点击 Install。
  4. 填写配置:选择认证方式(xoxc/xoxd 或 xoxp),填入对应令牌;可按需开启 Add Message Tool(发消息);企业版可改 User-Agent。
  5. 启用 MCP Server。

若遇到启动问题,可在 Claude Desktop 中禁用内置 node、改用宿主机 node 运行(这是 DXT 的已知问题)。

4.2 方式二:Cursor 一键安装

Cursor 提供了两个预置安装链接(分别对应 npx + xoxc/xoxd、npx + xoxp),点击后会自动写入 MCP 配置。务必把示例令牌替换成你自己的真实令牌。

4.3 方式三:npx(最快上手,Claude Desktop 推荐)

编辑 claude_desktop_config.json,在 mcpServers 中新增条目:

xoxp 令牌(推荐):

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "slack-mcp-server@latest", "--transport", "stdio"],
      "env": {
        "SLACK_MCP_XOXP_TOKEN": "xoxp-..."
      }
    }
  }
}

xoxc/xoxd 令牌(隐身模式):

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "slack-mcp-server@latest", "--transport", "stdio"],
      "env": {
        "SLACK_MCP_XOXC_TOKEN": "xoxc-...",
        "SLACK_MCP_XOXD_TOKEN": "xoxd-..."
      }
    }
  }
}

4.4 方式四:Docker(隔离运行,支持 stdio 与 SSE)

仓库自带 Dockerfile(基于 golang:1.24 构建,alpine 生产镜像,默认 streamable-http 传输、端口 5000)与 docker-compose.yml。

stdio 方式直接跑:

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

docker-compose 方式(SSE 常驻服务):

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   # 填入第 1 步获取的令牌
docker-compose up -d

仓库内的 compose 文件展示了完整的运维要点:通过命名卷持久化 .users_cache.json 与 .channels_cache.json 两个缓存文件,env_file 注入 .env,并将服务绑定到 0.0.0.0:3001。

4.5 使用 SSE 传输 + mcp-remote(远程/联网场景)

当需要把服务器部署到远端供 Claude Desktop 等客户端远程连接时,走 sse 模式并用 mcp-remote 包装:

{
  "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 换成 C:\\Progra~1\\nodejs\\npx.cmd。

暴露到公网时的 HTTPS 要求:mcp-remote 只接受 https 地址,因此可用 ngrok 临时隧道转发本地 SSE 端口:

ngrok http 3001

然后将生成的 https://xxxx.ngrok-free.app 端点填入 mcp-remote 参数。

4.6 控制台参数速查

参数 必填 说明
--transport 或 -t 是 传输方式,可选 stdio、sse、streamable-http

注意:README 表格只列了 stdio/sse,但 main.go 实际还支持 streamable-http,日志中标注的合法值也包含三者。

五、五个内置工具完整参数手册

所有工具的参数、默认值与取值约束都同时定义于 server.go 的注册代码中,与 README 保持一致,以下是完整整理。

5.1 conversations_history —— 拉取频道/DM 历史

  • channel_id(string,必填):频道 ID(Cxxxxxxxxxx)或名称(#general、@username_dm)。
  • include_activity_messages(boolean,默认 false):为 true 时返回 channel_join、channel_leave 等系统活动消息。实现上通过 msg.SubType != "" 过滤非活动消息(见 conversations.go)。
  • cursor(string,可选):分页游标,取上一次响应最后一行/列的 cursor 字段值;提供 cursor 时 limit 必须为空。
  • limit(string,默认 "1d"):可为时间范围(1d 1 天、1w 1 周、30d 30 天、90d 90 天——免费层级历史默认上限)或消息条数(如 50)。代码中数值型默认 50、表达式型默认 1d(见 conversations.go)。

5.2 conversations_replies —— 拉取线程回复

  • channel_id(string,必填):同上。
  • thread_ts(string,必填):线程父消息或线程内某条消息的时间戳,格式 1234567890.123456。
  • include_activity_messages(boolean,默认 false):同上。
  • cursor(string,可选):同上,提供时 limit 必须为空。
  • limit(string,默认 "1d"):同上。

5.3 conversations_add_message —— 发送消息(默认禁用)

安全设计:出于安全考虑,发消息能力默认关闭。必须设置 SLACK_MCP_ADD_MESSAGE_TOOL 环境变量才能启用(见下文环境变量章节)。

  • channel_id(string,必填):目标频道/DM,格式同上。
  • thread_ts(string,可选):提供则在指定线程内回复,否则发到频道本身。
  • payload(string,必填):消息内容,格式取决于 content_type。
  • content_type(string,默认 text/markdown):允许 text/markdown(如 # Hello, world!)与 text/plain(如 Hello, world!)。

在未启用或缺少权限时,处理器直接返回 write permission not allowed(见 conversations.go)。

5.4 conversations_search_messages —— 多维度检索消息

所有过滤器都可选,但全部省略时 search_query 必填。当 search_query 是 Slack 消息完整 URL 时(如 https://slack.com/archives/C1234567890/p1234567890123456),工具将只返回该 URL 对应的单条消息,其余参数全部忽略。

参数 类型/默认 说明
search_query string,可选 关键词(如 marketing report)或 Slack 消息 URL
filter_in_channel string,可选 限定频道,ID 或名称,如 C1234567890 / #general
filter_in_im_or_mpim string,可选 限定私信/群组私信,如 D1234567890 / @username_dm
filter_users_with string,可选 限定线程/私信中出现某用户,ID 或显示名,如 U1234567890 / @username
filter_users_from string,可选 限定来自某用户,如 U1234567890 / @username
filter_date_before string,可选 早于某日期,格式 YYYY-MM-DD,也支持 July、Yesterday、Today
filter_date_after string,可选 晚于某日期,格式同上
filter_date_on string,可选 精确某日,格式同上
filter_date_during string,可选 某时间段,格式同上
filter_threads_only boolean,默认 false 只返回线程消息
cursor string,默认 "" 分页游标
limit number,默认 20 返回条数上限,1~100 的整数

日期过滤最终被翻译成 Slack 原生搜索语法中的 before:、after:、on:、during: 等操作符(缓存实现中可直接看到这套 key 的解析逻辑,见 cache.go)。

5.5 channels_list —— 频道清单

  • channel_types(string,必填):逗号分隔的类型,允许值 mpim、im、public_channel、private_channel,如 public_channel,private_channel,im。全类型常量定义见 api.go。
  • sort(string,可选):popularity——按频道成员/参与人数排序。
  • limit(number,默认 100):1~999 的整数。
  • cursor(string,可选):分页游标。

注意:channels_list 与基于名称(#/@)的查找都强依赖频道缓存,缓存缺失时该工具完全不可用(详见第八节限制矩阵)。

六、两个 slack:// 目录资源

服务器暴露两个 MCP 资源,方便 LLM 在对话中直接读取工作区元数据(实现见 server.go 与 conversations.go):

6.1 slack://<workspace>/channels —— 频道目录

  • URI:slack://<workspace>/channels,MIME 类型 text/csv。
  • 字段:id(如 C1234567890)、name(如 #general、@username_dm)、topic、purpose、memberCount。
  • 覆盖公开频道、私密频道、单聊 DM 与群组私信(MPIM)。
  • 名称前缀由 api.go 的映射逻辑生成:IM 显示为 @用户名、MPIM 显示为 @名称(purpose 列出所有成员)、普通频道显示为 #名称。

6.2 slack://<workspace>/users —— 用户目录

  • URI:slack://<workspace>/users,MIME 类型 text/csv。
  • 字段:userID(如 U1234567890)、userName(如 john)、realName(如 John Doe)。
  • 实际工作区名由 AuthTest 从令牌对应的团队 URL 解析而来,因此同一个 URI 占位符可服务任意工作区(见 conversations.go)。

七、环境变量完整参考(Quick Reference)

以下表格合并 README 与 03-configuration-and-usage.md 的权威定义(带 * 表示三者按需选择其一):

变量 必填 默认 说明
SLACK_MCP_XOXC_TOKEN 是* nil Slack 浏览器令牌(xoxc-...)
SLACK_MCP_XOXD_TOKEN 是* nil Slack 浏览器 Cookie d(xoxd-...)
SLACK_MCP_XOXP_TOKEN 是* nil 用户 OAuth 令牌(xoxp-...),xoxc/xoxd 的替代方案
SLACK_MCP_PORT 否 13080 SSE/HTTP 监听端口
SLACK_MCP_HOST 否 127.0.0.1 SSE/HTTP 监听主机(streamable-http 默认 0.0.0.0)
SLACK_MCP_SSE_API_KEY 否 nil SSE 传输的 Bearer 鉴权令牌
SLACK_MCP_PROXY 否 nil 出站请求代理 URL
SLACK_MCP_USER_AGENT 否 nil 自定义 User-Agent(企业 Slack 环境)
SLACK_MCP_CUSTOM_TLS 否 nil 基于 User-Agent 向 Slack 服务器发起自定义 TLS 握手(企业环境)
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 启用发消息能力:true/1 对所有频道开放;逗号分隔的频道 ID 列表做白名单;! 前缀表示"除指定频道外全部允许";空值默认禁用
SLACK_MCP_ADD_MESSAGE_MARK 否 nil 启用后,发送的新消息自动标记为已读
SLACK_MCP_ADD_MESSAGE_UNFURLING 否 nil 允许 Slack 展开链接;或传逗号分隔域名白名单(如 github.com,slack.com)只对白名单域名展开;若文本同时含白名单与未知域名,出于安全将整体禁用展开
SLACK_MCP_USERS_CACHE 否 .users_cache.json 用户缓存文件路径
SLACK_MCP_CHANNELS_CACHE 否 .channels_cache_v2.json 频道缓存文件路径
SLACK_MCP_LOG_LEVEL 否 info 日志级别:debug、info、warn、error、panic、fatal

7.1 发消息工具的高级配置(源码佐证)

SLACK_MCP_ADD_MESSAGE_TOOL 的取值校验在启动时完成(见 main.go):

  • 空值、true、1 直接通过(空值 = 禁用,true/1 = 全量开放)。
  • 逗号分隔列表会被拆分为条目;! 前缀条目(排除)与普通条目(允许)不能混用,否则启动直接报错 cannot mix allowed and disallowed (! prefixed) channels。
  • 其余环境变量(日志级别、JSON 日志格式 SLACK_MCP_LOG_FORMAT、颜色 SLACK_MCP_LOG_COLOR 等)也在 main.go 的 logger 构建逻辑中处理;stdio 传输下日志自动输出到 stderr,避免污染与客户端通信的 stdout。

7.2 企业 Slack 环境(进阶)

如果你的工作区属于 Enterprise Slack 且安全策略较高,官方文档建议:把 SLACK_MCP_USER_AGENT 设为提取 xoxc/xoxd 时浏览器实际的 User-Agent 字符串,并开启 SLACK_MCP_CUSTOM_TLS 启用自定义 TLS 握手,使服务器对外表现得更像真实浏览器——这是部分高安全环境下服务器能否正常工作的关键。

八、缓存机制与功能限制矩阵

用户缓存与频道缓存是决定服务器功能完整度的关键开关。README 给出了明确的限制矩阵:

用户缓存 频道缓存 功能限制
✗ ✗ 无缓存、无用户数据上下文增强;channels_list 完全不可用;conversations_* 能力受限:无法按 @userHandle / #channel-name 搜索或获取消息
✓ ✗ 频道缓存缺失,channels_list 仍完全不可用;conversations_* 同样受限:无法按 @userHandle / #channel-name 搜索或获取消息
✓ ✓ 无限制,服务器功能完整

从实现看,用户与频道缓存分别在启动时写入 SLACK_MCP_USERS_CACHE(默认 .users_cache.json)与 SLACK_MCP_CHANNELS_CACHE(默认 .channels_cache_v2.json),目的就是避免每次冷启动重复调用 Slack 的 users/conversations API。此外,仓库还内置了一套基于 Slack 官方导出数据的只读评估缓存(SLACK_EXPORT_DIR,默认 ./slack_mcp_eval_export,见 api.go 与 cache.go),支持离线的历史、搜索与频道枚举演示——缓存客户端对写操作会直接返回 write permission not allowed(见 cache.go)。

九、调试与安全实践

9.1 调试工具

# 用 MCP Inspector 以 stdio 传输启动服务器进行交互调试
npx @modelcontextprotocol/inspector go run mcp/mcp-server.go --transport stdio

# 查看 Claude Desktop 的 MCP 日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

服务器本身也内置了工具级日志中间件,每次工具调用都会记录工具名、参数与耗时(见 server.go),配合 SLACK_MCP_LOG_LEVEL=debug 可获得完整调用链。

9.2 安全要点

  • 绝不分享令牌:xoxc/xoxd/xoxp 都是你的账号凭证,等同于账号本身,泄露即意味着工作区数据可被读取。
  • 妥善保管 .env 文件:加入 .gitignore,避免提交到仓库。
  • 发消息能力默认关闭:只有明确设置 SLACK_MCP_ADD_MESSAGE_TOOL 才开放;生产环境建议用白名单列表精确限定可写频道,而非直接设 true。
  • 不推荐设置 SLACK_MCP_SERVER_CA_INSECURE=true(信任所有不安全连接)。
  • 本项目遵循 MIT 许可(见 LICENSE),且非 Slack 官方产品。

十、总结

Klavis 仓库的 Slack MCP Server 把 Slack 工作区的读取、检索与受限写入能力标准化为 MCP 工具与资源,覆盖了从单机 Claude Desktop(stdio + npx)到远程多客户端(SSE + mcp-remote + HTTPS)的完整部署形态。掌握本文内容后,你可以:

  1. 用 Stealth 模式(xoxc/xoxd)快速接入、零应用安装;或改用 xoxp 用户 OAuth 获得更规范的权限管理。
  2. 按需选择 DXT / Cursor / npx / Docker 任一安装路径,在 5 分钟内跑通。
  3. 熟练使用 5 个工具与 2 个资源,实现按日期/条数分页拉取历史、线程追踪、多维检索与受控发信。
  4. 通过用户/频道缓存与环境变量的正确组合,避开"名称解析不可用、channels_list 失效"的功能陷阱,并借助代理、企业 TLS 与 SSE 鉴权适配复杂网络环境。

相关配套文档与源码请继续阅读:认证设置、安装指南、配置与使用,以及 工具注册源码 与 处理器实现。

登录后查看全文
klavis