Slack

@mindstone/mcp-server-slack

Slack 工作区 MCP 服务——通过 Slack Web API 管理频道、消息、线程、回应、用户、文件、书签和定时消息。

支持多工作区的 Slack MCP。由宿主驱动的 OAuth、存储在磁盘上的各工作区凭据文件，以及每次发布前的安全审查。

状态

• 版本： 0.3.0 · npm
• 认证： OAuth（由宿主协调）(SLACK_CLIENT_SECRET)
• 工具： 39（消息、频道、线程、用户、文件、置顶项）
• 接口： cloud-api
• 机器可读： STATUS.json

为什么开发它

我们开始构建这个连接器时，Slack 尚未发布官方 MCP 服务——该服务后来才推出（于 2026 年 2 月宣布，并于 2026 年 4 月普遍开放）。当时可用的社区 Slack MCP 服务各有可取之处，但没有一个能同时满足以下需求：为中小型工作区快速查找用户名、使用适用于现代 Slack 的正确提及格式（大多数服务仍使用已弃用的 link_names=true）、同一用户账户支持多个 Slack 工作区，以及令令牌保留在用户自己的设备上。Slack 的官方服务现已推出，可满足许多使用场景。我们仍在维护这个服务，因为登录流程由宿主应用处理，每个工作区都有一个由用户掌控、存储在磁盘上的凭据文件，而且每次发布前，连接器都会经过我们自己的安全审查。

交互示例

“查找 Alice 在 #q3-planning 中最近发的消息，并添加 :eyes: 回应。”

宿主调用的工具：

1. lookup_user_by_email——将 Alice 的电子邮件地址解析为她的 Slack 用户 ID。
2. search_slack_messages——在 #q3-planning 中搜索她最近发的消息，并返回频道和时间戳。
3. add_slack_reaction——为该消息添加 eyes 回应。

响应（节选）：

{
  "match": {
    "channel": "C08X...",
    "ts": "1715953812.004200",
    "user": "U07Z...",
    "text": "Pushed the updated forecast to the doc, ready for review."
  },
  "reaction": {
    "ok": true,
    "name": "eyes"
  }
}

要求

• Node.js 20+
• npm
• 能执行 Slack OAuth 流程并将各工作区令牌文件写入 ${SLACK_CONFIG_PATH}/workspaces/{teamId}.json 的宿主应用。此服务会读取这些文件；它本身不会发起 OAuth。

一键安装

点击按钮后，宿主将提示你填写：SLACK_CONFIG_PATH、SLACK_TEAM_ID、SLACK_CLIENT_SECRET、SLACK_REQUEST_TIMEOUT_MS、SLACK_MAX_RETRIES。

{
  "mcpServers": {
    "Slack": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-slack"
      ],
      "env": {
        "SLACK_CONFIG_PATH": "",
        "SLACK_TEAM_ID": "",
        "SLACK_CLIENT_SECRET": "",
        "SLACK_REQUEST_TIMEOUT_MS": "60000",
        "SLACK_MAX_RETRIES": "10"
      }
    }
  }
}

快速开始

安装和构建

cd <path-to-repo>/connectors/slack
npm install
npm run build

npx（发布后使用）

npx -y @mindstone/mcp-server-slack

本地运行

node dist/index.js

配置

此服务旨在与自行执行 Slack OAuth 流程的宿主应用配合运行。宿主会将凭据写入磁盘；此服务负责读取。

必需的环境变量

• SLACK_CONFIG_PATH — Slack 配置目录的路径（由宿主管理）。其中包含 config.json（工作区元数据）和 workspaces/{teamId}.json（每个工作区的令牌，权限模式为 0600）。
• SLACK_TEAM_ID — 工作区团队 ID（每个工作区一个实例）。

可选的环境变量

• SLACK_CLIENT_ID — OAuth Connected App 客户端 ID。仅在刷新轮换型令牌时需要。已保存的非轮换型令牌无需此项即可直接授权调用 Slack API。如果需要刷新但未设置此变量，服务会明确报错 REFRESH_NO_CLIENT_CREDENTIALS，并指示宿主重新进行身份验证。
• SLACK_CLIENT_SECRET — OAuth Connected App 客户端密钥。适用条件与 SLACK_CLIENT_ID 相同。
• SLACK_DISABLE_REFRESH — 设置为 1，可在此端禁用令牌刷新。令牌过期时，服务将以结构化的 auth_required 响应安全失败，而不会尝试通过 oauth.v2.access 刷新。云端使用时请设置此项，使桌面端成为唯一的刷新权限方，避免争用一次性刷新令牌。
• SLACK_REQUEST_TIMEOUT_MS — 覆盖默认的 60s 上游超时时间。必须为小于或等于 300000（5 分钟）的正整数。
• MCP_WORKSPACE_PATH — 限制 upload_slack_file 读取文件的目录。拒绝访问此目录之外的路径（包括指向目录外的符号链接）。未设置时，默认为系统临时目录。

身份验证流程

宿主会调用 authenticate_slack_workspace 工具。开源服务会返回如下形式的结构化 auth_required 响应：

{
  "status": "auth_required",
  "user_action": {
    "id": "slack.connect_workspace",
    "label": "Connect Slack",
    "instruction": "Click \"Connect Slack\" in the side panel to authorise the workspace."
  },
  "agent_action": {
    "instruction": "Tell the user to click the Connect Slack button in the connector settings to authorise. Then call list_slack_workspaces to verify."
  },
  "setupToolName": "authenticate_slack_workspace"
}

宿主的 MCP 服务会识别此响应结构，并将请求分派给已注册的 Slack OAuth 协调器（桌面浏览器流程）。用户登录后，宿主会将令牌写入 ${SLACK_CONFIG_PATH}/workspaces/{teamId}.json，服务会在下一次调用时读取这些令牌。

开源服务绝不会自行启动 OAuth。

宿主配置示例

此服务专为由宿主编排 OAuth 而设计：宿主会将各工作区的令牌文件写入磁盘，服务再读取这些文件。以下示例展示了环境变量的格式——工具调用成功前，宿主应用负责填充 ${SLACK_CONFIG_PATH}/workspaces/{teamId}.json。

Claude Desktop / Cursor

{
  "mcpServers": {
    "Slack": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-slack"],
      "env": {
        "SLACK_CONFIG_PATH": "/absolute/path/to/slack-config",
        "SLACK_TEAM_ID": "T0123ABCD",
        "SLACK_CLIENT_ID": "your-slack-app-client-id",
        "SLACK_CLIENT_SECRET": "your-slack-app-client-secret"
      }
    }
  }
}

在宿主为该团队写入 ${SLACK_CONFIG_PATH}/workspaces/T0123ABCD.json 之前，每次工具调用都会返回结构化的 auth_required 响应（参见上文的身份验证流程）。

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "Slack": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/slack/dist/index.js"],
      "env": {
        "SLACK_CONFIG_PATH": "/absolute/path/to/slack-config",
        "SLACK_TEAM_ID": "T0123ABCD",
        "SLACK_CLIENT_ID": "your-slack-app-client-id",
        "SLACK_CLIENT_SECRET": "your-slack-app-client-secret"
      }
    }
  }
}

工具（39）

身份验证

• authenticate_slack_workspace — 返回结构化的 auth_required 响应；OAuth 流程由宿主驱动。
• list_slack_workspaces — 检查 Slack 连接状态（是否已连接、令牌健康状况、是否即将过期）。

消息

• search_slack_messages — 搜索所有频道（支持 Slack 搜索修饰符）。提供 to_me、after 或 before 时，可以省略 query；这些参数一个都不提供的调用会被拒绝。当已连接的应用具有细粒度 search:read.* 范围时，使用 Slack 的 Real-Time Search API（assistant.search.context）；否则回退到旧版 search.messages，其结果同样完整。响应会在 search_backend 中记录所用后端；该字段仅用于诊断，且不会向用户说明发生了回退，因为启用 Real-Time Search 路径需要更改应用配置，而非请求者能够完成。仅当因安装范围的拒绝（missing_scope、not_allowed_token_type、feature_not_enabled、端点弃用代码）而发生回退时，才会按工作区缓存；资源特定的 access_denied 会作为普通错误显示，并在下次调用时重试 RTS。
• get_slack_saved_messages — 获取稍后查看的已保存消息（使用 is:saved）。后端报告方式与 search_slack_messages 相同。
• get_slack_message_by_link — 根据永久链接 URL 获取消息。
• compose_slack_message — 发送前打开内嵌可编辑的撰写表单；用户点击 Send 后，表单会通过 post_slack_message 发布消息。
• post_slack_message — 发布消息；内置 DM 收件人验证。禁止向自己发送 DM，并会改用 send_myself_a_note（用户令牌发出的自我 DM 不会触发通知）。
• reply_to_slack_thread — 回复现有消息串。
• schedule_slack_message — 定时发送消息。禁止向自己发送 DM（目前尚不支持定时发送给自己的备注）。
• list_scheduled_slack_messages — 列出待发送的定时消息（可按频道筛选），并提供取消这些消息所需的 ID。
• delete_scheduled_slack_message — 在定时消息发送前取消它。
• update_slack_message — 编辑你发布的消息。
• delete_slack_message — 永久删除你发布的消息。
• send_myself_a_note — 给自己发送一条确实会触发通知的备注（由机器人向已验证身份的用户发送 DM）。请使用此工具代替用户令牌发出的自我 DM，用于“随手记下点什么”或设置提醒。

频道

• list_slack_channels — 列出频道（支持筛选和分页）。
• get_slack_channel_history — 获取频道中的近期消息。
• create_slack_channel — 创建新频道（公开或私有）。
• mark_slack_channel_as_read — 将消息标记为已读，直至指定时间戳。
• get_slack_unread_messages — 根据你的已读位置获取未读消息。
• invite_user_to_channel — 批量将用户添加到频道。

消息串

• get_slack_thread_replies — 获取消息串中的所有回复。

表情回应

• add_slack_reaction — 为消息添加表情回应。
• remove_slack_reaction — 移除你对消息添加的表情回应。
• list_slack_emoji — 列出工作区的自定义表情（名称 → URL/别名，均封装在 <untrusted-content> 信封中）。违反 Slack 表情名称/值约束的条目会被丢弃并报告（omitted_invalid_entries），绝不会转发。

置顶项

• list_slack_pins — 列出频道中置顶的消息。
• pin_slack_message — 将消息置顶到频道。
• unpin_slack_message — 从频道的置顶项中移除消息（不会删除消息本身）。

用户

• list_slack_users — 列出活跃用户（名称筛选会自动分页）。
• get_slack_user_profile — 获取用户的详细个人资料。
• lookup_user_by_email — 通过完全匹配的电子邮件查找用户（首选的解析方式）。
• open_slack_dm — 与用户开启私信（返回私信频道和已验证的收件人身份）。

文件

• download_slack_file — 按 ID 或 URL 下载文件附件。
• upload_slack_file — 上传本地文件（仅限工作区范围，读取无竞争；最大 50MB），并可选择分享到频道或线程。使用 3 步外部上传流程。

工作区

• add_slack_bookmark — 向频道添加书签。
• list_slack_bookmarks — 列出频道的书签。
• add_slack_reminder — [EXPERIMENTAL] 创建提醒（Slack API 已部分弃用；建议使用 schedule_slack_message）。
• list_slack_reminders — [EXPERIMENTAL] 列出你的提醒。
• complete_slack_reminder — [EXPERIMENTAL] 将提醒标记为已完成。
• delete_slack_reminder — [EXPERIMENTAL] 永久删除提醒。

安全说明

• Slack 自有下载 URL 防护 — download_slack_file 会验证 Slack 提供的 url_private_download 是否为 HTTPS，且域名为 slack.com 或 *.slack.com，然后才附加工作区 bearer token。下载辅助程序还会设置 redirect: 'manual'，并重新验证每一跳重定向，因此即使被入侵的 Slack 边缘节点将请求 302 重定向到攻击者控制的主机，也不会泄露 bearer token（在 0.1.3 中添加，以修复问题 slack-010）。
• 不可信内容封装 — 根据 AGENTS.md 不变量 #6，所有返回外部文本的工具都会使用 <untrusted-content source="…">…</untrusted-content> 封装内容，并对闭合标签进行转义。这适用于消息文本、频道主题/用途、搜索结果、线程回复、未读消息，以及下载文件的内容/名称。主机在向模型展示工具输出时必须保留封装（在 0.1.3 中添加，以修复问题 slack-001..007）。
• 令牌持久化的原子性与持久性 — 令牌文件通过临时文件 + fsync + rename 写入，随后执行 chmod 0600，因此即使写入期间发生崩溃，也不会丢失 Slack 的一次性刷新令牌。
• 区分刷新失败类型 — 瞬时网络错误、HTTP 429 速率限制、Slack 身份验证拒绝（invalid_grant）以及格式错误的响应会产生不同的错误代码，便于主机正确处理，且不会重试无法恢复的失败。
• 不包含主机内部词汇 — 发布的构件中明确不包含主机侧桥接标识符和打包的 HTTP 路径（通过 prepublishOnly 阶段运行的 scripts/check-no-bridge-strings.sh 强制执行；此外，scripts/check-internal-refs.mjs 也会检查，该脚本还会通过 npm run security:internal-refs 运行，并额外拒绝 src/ 和 dist/ 中的内部问题跟踪引用）。
• 上传源文件读取无竞争 — upload_slack_file 会验证源文件路径位于工作区内，然后只打开一次文件（不跟随符号链接、非阻塞），通过对已打开的文件描述符执行 fstat 来强制限定为常规文件并遵守 50MB 上限；随后会将该描述符的 dev+inode 与重新解析的受限路径进行复核（可防止验证后替换，包括替换祖先目录），并通过该描述符读取字节，同时对实际读取的数据强制执行大小上限。
• 添加路径上的封装一致性 — add_slack_bookmark 和 add_slack_reminder 会像列表路径一样封装 Slack 返回的标题/文本，并对闭合标签进行转义。

完整的实现层级说明（请求超时组合、MSW 请求清单、令牌文件错误状态、服务端版本漂移检查等）见 docs/connectors/slack-cohort-hygiene.md。

实时探测

实时探测门禁已提交至 test/live-probe.ts。它不会自动运行；请手动触发：

LIVE_PROBE_BOT_TOKEN=xoxb-... \
LIVE_PROBE_USER_TOKEN=xoxp-... \
LIVE_PROBE_TEAM_ID=T... \
npm run probe:live

探测会针对打包后的 tarball（而非工作区源代码）运行，执行 initialize + tools/list + 5 次只读工具调用 + 2 次写入工具调用，并记录 search.messages 的 P95 延迟，以验证 60s 超时默认值。

默认情况下，探测为只读：仅当设置了 LIVE_PROBE_TEST_CHANNEL_ID 时，才会运行写入探测（post_slack_message、add_slack_reaction）；否则会跳过，探测仍会以 OK 状态退出。

发布门禁模式

发布前认证时，请运行：

LIVE_PROBE_BOT_TOKEN=xoxb-... \
LIVE_PROBE_USER_TOKEN=xoxp-... \
LIVE_PROBE_TEAM_ID=T... \
LIVE_PROBE_TEST_CHANNEL_ID=C... \
npm run probe:live:gate

probe:live:gate 会设置 LIVE_PROBE_REQUIRE_WRITES=1；如果缺少 LIVE_PROBE_TEST_CHANNEL_ID，或任一写入探测未能顺利完成，探测会失败而非跳过。请在准备发布版本前使用此模式。

许可证

FSL-1.1-MIT — 功能源代码许可证 1.1 版，未来许可证为 MIT。该软件将于 2030-04-08 转为 MIT 许可证。