slack-mcp-server

Slack MCP Server

一个 MCP（Model Context Protocol）服务，可通过编程方式访问 Slack 对话、讨论串和工作区信息。它旨在让 Claude 等 AI 助手通过标准化接口与 Slack 工作区交互。

什么是 MCP？

Model Context Protocol 是一种开放标准，可让 AI 助手安全地访问外部数据源和工具。此服务实现了 MCP，让 Claude 可以直接访问你的 Slack 工作区。

功能

📨 消息操作

• 读取频道消息：获取任意频道的近期消息，并灵活地按时间筛选
• 读取讨论串消息：访问完整的对话讨论串，包括所有回复
• 获取消息永久链接：生成指向特定消息的永久共享链接

🔍 发现与搜索

• 列出你的频道：列出你所属的所有频道（公开、私密、私信和群组私信）
• 搜索对话：使用 Slack 搜索功能，查找提及你或与你有关的消息

📊 元数据与上下文

• 获取频道信息：查看频道详情、主题、用途、成员数量和设置
• 获取用户信息：查询用户资料、电子邮件、职位、时区和状态信息

快速开始

选项 1：从 PyPI 安装（推荐）

使用此 MCP 服务最简单的方式是直接从 PyPI 安装：

# Install via pip
pip install slack-mcp-server-v2

# Or install via uvx (recommended for MCP servers)
uvx slack-mcp-server-v2

选项 2：从源代码安装

# Clone the repository
git clone https://github.com/stevenvo/slack-mcp-server.git
cd slack-mcp-server

# Install dependencies
pip install -r requirements.txt

安装后，你需要设置身份验证（见下文）。

身份验证

选项 1：用户令牌（推荐）

用户令牌使用你的个人 Slack 权限，可访问你所属的所有频道。

1. 前往 https://api.slack.com/apps
2. 创建新应用（或使用已有应用）
3. 前往 “OAuth & Permissions”
4. 添加以下 User Token Scopes：
   • channels:history - 查看公开频道中的消息
   • channels:read - 查看频道基本信息
   • groups:history - 查看私密频道中的消息
   • groups:read - 查看私密频道基本信息
   • im:history - 查看私信中的消息
   • im:read - 查看私信基本信息
   • mpim:history - 查看群组私信中的消息
   • mpim:read - 查看群组私信基本信息
   • users:read - 查看用户信息
   • search:read - 搜索消息
5. 将应用安装到你的工作区
6. 复制 “User OAuth Token”（以 xoxp- 开头）

选项 2：Bot 令牌

Bot 令牌的权限较少，但设置起来更简单，适合团队范围的访问。

1. 按照上述步骤 1-2 操作
2. 改为添加 Bot Token Scopes（列表相同，但位于 bot 区域）
3. 安装应用
4. 复制 “Bot User OAuth Token”（以 xoxb- 开头）
5. 邀请 bot 加入你要读取的频道：/invite @YourBotName

配置环境

创建 .env 文件：

cp .env.example .env

编辑 .env 并添加你的令牌：

# Use one of these:
SLACK_USER_TOKEN=xoxp-your-user-token-here
# OR
SLACK_BOT_TOKEN=xoxb-your-bot-token-here

Claude Code 配置

编辑 ~/.claude.json 文件，将此服务添加到 Claude Code：

使用 PyPI 包（推荐）

{
  "mcpServers": {
    "slack": {
      "command": "uvx",
      "args": ["slack-mcp-server-v2"],
      "env": {
        "SLACK_USER_TOKEN": "xoxp-your-user-token-here",
        "SLACK_WORKSPACE_URL": "https://your-workspace.slack.com"
      }
    }
  }
}

使用本地安装

如果你从源代码安装：

{
  "mcpServers": {
    "slack": {
      "command": "python",
      "args": ["/path/to/slack-mcp-server/server.py"],
      "env": {
        "SLACK_USER_TOKEN": "xoxp-your-user-token-here",
        "SLACK_WORKSPACE_URL": "https://your-workspace.slack.com"
      }
    }
  }
}

使用 Bot 令牌

如果你更倾向于使用 bot 令牌而不是用户令牌：

{
  "mcpServers": {
    "slack": {
      "command": "uvx",
      "args": ["slack-mcp-server-v2"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-bot-token-here",
        "SLACK_WORKSPACE_URL": "https://your-workspace.slack.com"
      }
    }
  }
}

注意：请记得邀请 bot 加入频道：/invite @YourBotName

验证安装

重启 Claude Code，并确认服务正在运行：

claude mcp list

你应该会在活动 MCP 服务列表中看到 slack。

可用工具

此服务提供 7 个 MCP 工具，用于与 Slack 交互：

📬 read_channel_messages

使用灵活的时间筛选条件，获取任意 Slack 频道中的近期消息。

参数：

名称	类型	必填	默认值	描述
channel_id	string	✅	-	Slack 频道 ID（例如，C1234567890）
lookback_hours	number	❌	24	从当前时间向前回溯的小时数
limit	number	❌	100	要获取的最大消息数（最大值：1000）

自然语言示例：

• “显示过去 24 小时内 #general 频道中的消息”
• “读取频道 C1234567890 过去 48 小时内的消息”
• “获取 C070PDRHQS1 中最新的 50 条消息”

**返回：**格式化后的消息，包含时间戳、用户提及、线程指示标记、回应和永久链接。

---

💬 read_thread_messages

读取对话线程中的所有消息，包括父消息及其所有回复。

参数：

名称	类型	必填	描述
channel_id	string	✅	线程所在频道的 ID
thread_ts	string	✅	线程时间戳（父消息的 ts 字段）

自然语言示例：

• “读取频道 C1234567890 中时间戳为 1699564800.123456 的完整线程”
• “显示对时间戳为 1699564800.123456 的消息的所有回复”

**返回：**完整线程，包含父消息及其所有回复，并以带有时间戳和回应的格式呈现。

---

📋 get_channel_info

获取 Slack 频道的详细元数据。

参数：

名称	类型	必填	描述
channel_id	string	✅	Slack 频道 ID

自然语言示例：

• “获取频道 C1234567890 的信息”
• “显示 #engineering 频道的详细信息”

**返回：**频道名称、ID、创建日期、成员数、隐私状态、主题和用途。

---

👤 get_user_info

查找任意 Slack 用户的详细个人资料信息。

参数：

名称	类型	必填	描述
user_id	string	✅	Slack 用户 ID（例如，U1234567）

自然语言示例：

• “获取用户 U1234567 的信息”
• “显示 @john.doe 的详细信息”

**返回：**用户的真实姓名、显示名称、电子邮件、职位、状态、时区，以及管理员/机器人标记。

---

📑 list_my_channels

列出你加入的所有频道，并支持不同的频道类型。

参数：

名称	类型	必填	默认值	描述
types	string	❌	public_channel,private_channel	以逗号分隔的频道类型

支持的类型：

• public_channel - 公开频道
• private_channel - 私密频道
• mpim - 群组私信
• im - 私信

自然语言示例：

• “列出我加入的所有频道”
• “显示我加入的所有私密频道”
• “列出我的所有私信”

**返回：**频道名称、ID、成员数和隐私标记。

---

🔍 search_my_conversations

搜索你参与或被提及的所有对话中的消息。

参数：

名称	类型	必填	默认值	描述
query	string	✅	-	搜索词
count	number	❌	20	结果数量（最大值：100）

自然语言示例：

• “在我的对话中搜索 ‘deployment’”
• “查找过去一周内提及 ‘bug fix’ 的消息”
• “搜索有关 ‘Q4 planning’ 的消息”

**返回：**匹配的消息，包含频道名称、用户信息、时间戳和永久链接。

---

🔗 get_message_permalink

生成指向特定 Slack 消息的永久可分享链接。

参数：

名称	类型	必填	说明
channel_id	string	✅	频道 ID
message_ts	string	✅	消息时间戳

自然语言示例：

• “获取频道 C1234567890 中时间戳为 1699564800.123456 的消息永久链接”
• “生成指向这条消息的链接”

返回： 即使工作区的 URL 发生变化，该永久 URL 仍然有效。

使用示例

在 Claude Code 中完成配置后，你可以使用自然语言与 Slack 工作区交互。以下是一些查询示例：

阅读消息

👤 "Show me the latest messages from #engineering"
🤖 [Claude fetches and displays recent messages with timestamps, users, and links]

👤 "What were the last 100 messages in the #product-updates channel from the past week?"
🤖 [Claude retrieves messages from the last 168 hours with limit of 100]

跟进消息串

👤 "Read the full thread that starts at timestamp 1699564800.123456 in channel C1234567890"
🤖 [Claude displays the entire conversation thread with all replies]

探索与搜索

👤 "List all channels I'm a member of"
🤖 [Claude shows all your public and private channels with member counts]

👤 "Search my Slack conversations for 'quarterly review'"
🤖 [Claude searches across all your messages and shows matches with context]

👤 "Find mentions of 'production deployment' in my conversations"
🤖 [Claude uses Slack search to find relevant messages]

获取上下文

👤 "Get info about channel C1234567890"
🤖 [Claude shows channel name, topic, member count, etc.]

👤 "Who is user U1234567?"
🤖 [Claude displays user profile with email, title, timezone]

👤 "Get me a permanent link to message 1699564800.123456 in #general"
🤖 [Claude generates a shareable permalink]

实用工作流

了解项目进展：

👤 "Show me all messages from #project-alpha in the last 3 days"

找到那项重要决策：

👤 "Search for messages about 'API migration decision'"

获取入职背景信息：

👤 "List all channels I'm in and show me the purpose of each"

查找频道 ID

方法 1：从 Slack URL 查找

进入频道后，URL 如下所示：

https://your-workspace.slack.com/archives/C1234567890/p1234567890

/archives/ 后面的部分就是频道 ID：C1234567890

方法 2：使用 MCP 服务

向 Claude 提问：

List all my channels

方法 3：在 Slack 中右键单击

1. 右键单击频道名称
2. 单击“复制链接”
3. 从 URL 中提取频道 ID

要求

• Python：3.10 或更高版本
• Slack 工作区：拥有创建和配置 Slack 应用的管理员权限
• Claude Code：支持 MCP 的最新版本
• 操作系统：macOS、Linux，或搭载 WSL 的 Windows

故障排除

“Missing required scopes”错误

你的 Slack 应用需要配置正确的 OAuth 权限范围。

解决方法：

1. 前往 https://api.slack.com/apps 并选择你的应用
2. 导航至“OAuth & Permissions”
3. 确保已添加“Authentication”部分中列出的所有必需权限范围
4. 将应用重新安装到工作区
5. 复制新令牌

“Channel not found”错误

对于 Bot 令牌：

# Invite the bot to the channel first
/invite @YourBotName

对于 User 令牌：

• 确认你是该频道的成员
• 检查频道 ID 是否正确（请参阅“查找频道 ID”部分）

“Not authenticated”错误

检查你的配置：

# Verify token is set correctly (check ~/.claude.json)
cat ~/.claude.json | grep -A 5 "slack"

# Ensure no extra whitespace
echo "$SLACK_USER_TOKEN" | wc -c

常见问题：

• 令牌已过期或已撤销
• 令牌字符串中有多余的空格或换行符
• 令牌类型错误（User 或 Bot）
• JSON 中的令牌未正确加引号

MCP 服务未运行

确认服务已加载：

# List all MCP servers
claude mcp list

# Check if slack server is running
claude mcp list | grep slack

检查日志中的错误：

# View recent MCP server logs
tail -f ~/.claude/debug/*.log

# Filter for slack-related errors
tail -f ~/.claude/debug/*.log | grep -i slack

常见解决方法：

1. 完全重启 Claude Code
2. 检查 ~/.claude.json 语法是否为有效 JSON
3. 确认 Python 版本：python --version（必须为 3.10+）
4. 手动测试服务：python server.py（如果从源代码安装）

SSL 证书错误

如果你在企业代理后方（如 Zscaler）：

# Set SSL certificate environment variable
export SSL_CERT_FILE=/path/to/your/ca-bundle.pem
export REQUESTS_CA_BUNDLE=/path/to/your/ca-bundle.pem

# Then reinstall
pip install slack-mcp-server-v2

速率限制

Slack API 有速率限制。如果触发限制：

• 减小 read_channel_messages 中的 limit 参数
• 增大 lookback_hours，以获取更少的消息
• 等待几分钟后再重试

速率限制提示：

Error: ratelimited

解决方法： 服务会自动处理速率限制，但你可能需要等待。

安全与隐私

令牌安全

• 切勿将令牌提交到版本控制中——默认情况下，.env 文件已加入 git 忽略列表
• 令牌泄露后立即撤销，网址：https://api.slack.com/apps
• 在生产环境中使用环境变量，切勿将令牌硬编码
• 定期轮换令牌，作为安全最佳实践的一部分

数据访问

User 令牌：

• 可以访问你在 Slack 中能够查看的所有内容
• 使用你的个人权限
• 可以查看你加入的所有频道
• 更适合个人使用

Bot 令牌：

• 仅限访问已邀请该 Bot 的频道
• 与个人身份分离
• 更适合团队或共享配置
• 控制粒度更细

企业环境

如果你在企业环境中使用：

• 创建 Slack 应用前，请先咨询 IT／安全团队
• 注意数据保留和合规政策
• 考虑使用机器人令牌以便保留审计轨迹
• 可能需要配置 SSL 证书（参见故障排除）

限制

• 只读：此服务只读取数据，无法发布消息或修改内容
• 速率限制：受 Slack API 速率限制约束（Tier 3：约每分钟 50 次请求）
• 令牌范围：只能访问令牌获准查看的频道／对话
• 消息历史：受 Slack 工作区的消息保留政策限制

贡献

欢迎贡献！以下是你可以提供帮助的方式：

报告问题

发现了 Bug 或有功能请求？

1. 查看现有问题：https://github.com/stevenvo/slack-mcp-server/issues
2. 创建新问题，并包含：
   • 清晰描述问题／功能
   • 重现步骤（针对 Bug）
   • 预期行为与实际行为
   • 你的环境（Python 版本、操作系统、Claude Code 版本）

拉取请求

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 进行更改
4. 充分测试
5. 使用清晰的提交消息：git commit -m "Add amazing feature"
6. 推送到你的 Fork：git push origin feature/amazing-feature
7. 发起拉取请求

开发环境设置

# Clone your fork
git clone https://github.com/YOUR_USERNAME/slack-mcp-server.git
cd slack-mcp-server

# Install in development mode
pip install -e .

# Make changes and test
python server.py

更新日志

v0.1.0（2025-01-06）

• 首次发布
• 提供 7 个用于读取 Slack 对话的核心工具
• 支持用户令牌和机器人令牌
• 已发布到 PyPI 和 MCP 注册表
• 提供完整文档

路线图

未来可能增强的功能：

• 支持 Slack Enterprise Grid
• 按用户或表情回应筛选消息
• 将对话导出为不同格式
• 支持 Slack Connect 频道
• 使用缓存减少 API 调用
• 支持 Webhook，以便实时更新

欢迎在 GitHub Issues 中提出建议！

相关项目

• Model Context Protocol - MCP 规范
• MCP Registry - 浏览更多 MCP 服务
• Slack SDK for Python - 底层库
• Claude Code - 支持 MCP 的 AI 助手

支持

• 文档：你正在阅读的就是文档！
• 问题：https://github.com/stevenvo/slack-mcp-server/issues
• 讨论：https://github.com/stevenvo/slack-mcp-server/discussions
• Slack API 文档：https://api.slack.com/docs

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

版权所有 (c) 2025 Steven Vo

---

为 MCP 社区倾心打造 ❤️

如果你觉得这个项目有用，请在 GitHub 上为仓库点亮 ⭐！