Slack Bot MCP

Slack MCP 服务器

一个基于TypeScript的模型上下文协议（MCP）服务器，提供全面的Slack工作区集成。该服务器使AI助手能够通过MCP协议与Slack频道、用户、消息、文件等进行交互。

目录

• 特点/特性
• 先决条件
• 安装与设置

- 步骤1：项目设置 - 步骤2：创建Slack应用 - 第三步：配置环境 - 步骤4：构建与验证

• 测试您的设置
• 使用
• 工具示例
• 故障排除

特点/功能

渠道管理

• 列出频道 - 列出工作区频道并提供过滤选项
• 获取频道信息 - 获取特定频道的详细信息
• 创建频道 - 创建新的公共或私有频道
• 归档频道 - 归档频道

用户管理

• 列出用户 - 列出工作区中的所有用户
• 获取用户信息 - 获取详细的用户资料信息
• 邀请加入频道 - 邀请用户加入频道

信息传递/消息服务

• 发送消息 - 向频道发送文本消息
• 更新消息 - 更新现有消息
• 删除消息 - 删除消息
• 获取频道历史记录 - 分页获取消息历史
• 搜索消息 - 在整个工作区中搜索消息
• 发送格式化消息 - 使用 Block Kit 格式发送消息

文件操作

• 上传文件 - 将文件上传到频道

反应

• 添加反应 为消息添加表情符号反应
• 移除反应 - 移除表情符号反应

工作区信息

• 获取团队信息 - 获取工作区/团队信息

先决条件

在开始之前，请确保您已具备：

• Node.js 18 或更高版本 - 与以下内容核对： node --version
• npm - 与以下内容核对： npm --version
• Slack工作区管理员访问权限 - 您需要获得创建和安装应用程序的权限
• 预计设置时间： 约20分钟

安装与设置

步骤1：项目设置（5分钟）

克隆仓库并安装依赖项：

# Clone the repository
git clone 
cd slack-bot-mcp

# Install dependencies
npm install

✓ 验证： 跑 npm list @modelcontextprotocol/sdk 确认已安装MCP SDK。

______________________________________________________________________

步骤2：创建Slack应用（10分钟）

2.1 创建应用程序

1. 访问 https://api.slack.com/apps
2. 点击 “创建新应用” → “从零开始”
3. 输入应用名称（例如，“MCP Bot”）并选择您的工作区
4. 点击 “创建应用”

2.2 配置OAuth范围

导航至 “OAuth & 权限” 在侧边栏中，滚动到 “Scopes”翻译成中文是“范围”或“作用域”，并添加这些 机器人令牌作用域：

💡 提示： 每个作用域对于特定工具的功能运行都是必需的。缺少作用域将导致“missing_scope”错误。

2.3 安装到工作区

1. 滚动到 “为您的工作区提供的OAuth令牌”
2. 点击 “安装到工作区”
3. 检查权限并点击 “允许”

2.4 复制您的机器人令牌

1. 安装后，您会看到 “机器人用户OAuth令牌”
2. 点击 “复制” （令牌以...开始 xoxb-)
3. 请妥善保管这个令牌——下一步会需要用到它

✓ 验证： 您的令牌应该看起来像这样： xoxb---

______________________________________________________________________

步骤3：配置环境（2分钟）

创建您的环境配置：

# Copy the example file
cp .env.example .env

编辑 .env 并添加您的机器人令牌：

SLACK_BOT_TOKEN=xoxb-your-actual-token-here

✓ 验证： 运行此命令以确认您的令牌已加载：

node -e "require('dotenv').config(); console.log('Token loaded:', !!process.env.SLACK_BOT_TOKEN)"

你应该看到： Token loaded: true

⚠️ 常见问题： 确保你的令牌以……开头 xoxb- （不是 xoxp- 或者 xoxa-）

______________________________________________________________________

步骤4：构建并验证（3分钟）

构建TypeScript项目：

npm run build

✓ 验证： 确认 build/ 目录已创建：

ls build/index.js

你应该能看到编译后的结果 index.js 文件。

______________________________________________________________________

测试您的设置

在与Claude Desktop集成之前，请测试确保一切正常运行：

使用MCP Inspector

MCP Inspector 提供了一个图形用户界面 (GUI) 来测试您的工具：

npx @modelcontextprotocol/inspector node build/index.js

这将打开一个网页界面，您可以在其中：

• 查看所有可用工具
• 使用样本输入测试单个工具
• 查看响应并调试错误

快速测试命令

在MCP检查器中尝试这些简单测试：

1. 列出频道：

- 工具： list_channels - 参数： {"limit": 5} - 预期结果：您工作区频道的列表

1. 获取团队信息：

- 工具： get_team_info - 参数： {} - 预期：您的工作区名称及详细信息

1. 列出用户：

- 工具： list_users - 参数： {"limit": 5} - 预期结果：工作区用户列表

✓ 成功指标： 如果这些命令返回数据（而非错误），则说明您的设置是正确的！

⚠️ 故障排除： 如果你看到“invalid_auth”或“token_revoked”，请仔细检查你的 SLACK_BOT_TOKEN 在……里（或“在……中”） .env 文件。

______________________________________________________________________

使用方法

使用Claude Desktop

在您的Claude Desktop配置文件中添加：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%/Claude/claude_desktop_config.json

选项1：直接从GitHub获取（推荐）

使用 npx 直接从GitHub仓库运行：

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": [
        "github:Hais/slack-bot-mcp"
      ],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

好处：

• ✓ 无需本地安装
• ✓ 始终使用最新版本
• ✓ 更简单的配置
• ✓ 在任何安装了Node.js的机器上都能运行

选项2：本地安装

用于本地开发或离线使用：

{
  "mcpServers": {
    "slack": {
      "command": "node",
      "args": ["/absolute/path/to/slack-bot-mcp/build/index.js"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token-here"
      }
    }
  }
}

本地安装设置：

1. 克隆并构建项目（参见 安装与设置)
2. 替换 /absolute/path/to/slack-bot-mcp 包含您的完整项目路径

- 通过运行来找到它 pwd 在你的项目目录中 - 示例： /Users/yourname/projects/slack-bot-mcp/build/index.js

______________________________________________________________________

重要提示：

1. 令牌配置： 设定；套装 SLACK_BOT_TOKEN 在上面所示的配置文件中

- 配置文件中的token优先级高于 .env 文件 - 确保您的令牌安全，切勿将其提交到版本控制系统中

1. 需要重启： 编辑配置文件后，重启Claude桌面版

1. 首次运行： 第一次使用 npx它将下载并缓存该包（可能需要几秒钟）

✓ 验证： 打开Claude桌面版并输入：“列出我的Slack频道”。如果配置正确，Claude将使用 list_channels 工具。

与其他MCP客户端一起

服务器运行在stdio传输层，并且可以与任何MCP客户端集成：

node build/index.js

开发模式

对于支持热重载的开发：

npm run dev

工具示例

列出频道

{
  "name": "list_channels",
  "arguments": {
    "types": "public_channel,private_channel",
    "exclude_archived": true,
    "limit": 50
  }
}

发送消息

{
  "name": "send_message",
  "arguments": {
    "channel": "C1234567890",
    "text": "Hello from MCP!"
  }
}

使用 Block Kit 发送格式化消息

{
  "name": "send_formatted_message",
  "arguments": {
    "channel": "C1234567890",
    "text": "Fallback text",
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "mrkdwn",
          "text": "*Hello* from MCP with _formatting_!"
        }
      }
    ]
  }
}

搜索消息

{
  "name": "search_messages",
  "arguments": {
    "query": "important announcement",
    "count": 10,
    "sort": "timestamp"
  }
}

上传文件

{
  "name": "upload_file",
  "arguments": {
    "channels": ["C1234567890"],
    "content": "File content here",
    "filename": "report.txt",
    "title": "Monthly Report"
  }
}

添加反应

{
  "name": "add_reaction",
  "arguments": {
    "channel": "C1234567890",
    "timestamp": "1234567890.123456",
    "name": "thumbsup"
  }
}

所需的OAuth范围

确保您的Slack应用拥有这些权限范围：

项目结构

slack-bot-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── channels.ts       # Channel management tools
│   │   ├── users.ts          # User management tools
│   │   ├── messages.ts       # Messaging tools
│   │   ├── files.ts          # File upload tool
│   │   ├── reactions.ts      # Reaction tools
│   │   └── workspace.ts      # Workspace info tool
│   ├── config/
│   │   └── credentials.ts    # Environment config loader
│   ├── types/
│   │   └── slack.ts          # TypeScript interfaces
│   └── utils/
│       ├── slack-client.ts   # Slack API wrapper
│       └── validators.ts     # Zod input validators
├── build/                    # Compiled JavaScript
├── .env                      # Your environment variables
├── .env.example             # Environment template
├── package.json
├── tsconfig.json
└── README.md

故障排除

设置问题

“需要设置 SLACK_BOT_TOKEN 环境变量”

原因： 服务器找不到您的机器人令牌。

解决方案：

1. 验证 .env 文件存在于项目根目录中： ls -la .env
2. 检查令牌格式： cat .env （应显示 SLACK_BOT_TOKEN=xoxb-...)
3. 如果使用Claude桌面配置，请确保令牌已放置在 env 部分；章节
4. 更改后请重启您的MCP客户端

“缺少必需的OAuth作用域”

原因： 您的机器人令牌没有必要的权限。

解决方案：

1. 访问 https://api.slack.com/apps → 选择您的应用 → “OAuth & 权限”
2. 添加缺失的作用域（错误信息会指明是哪一个）
3. 点击“重新安装到工作区”（在添加作用域后必须执行此操作）
4. 复制新的机器人令牌并更新您的配置

💡 注： 更改范围后，您必须重新安装应用程序。旧的令牌不会自动获得新权限。

运行时问题

“频道未找到”或“用户未找到”

原因： 你正在使用频道/用户名而不是ID。

解决方案：

• 频道ID以...开头 C （公开）， G （私人），或 D (直接邮件)
• 用户ID以……开头 U
• 使用 list_channels 或者 list_users 用于查找正确ID的工具

示例：

// ❌ Wrong
{"channel": "general"}

// ✓ Correct
{"channel": "C1234567890"}

“无效的授权”或“令牌被撤销”

原因： 机器人令牌不正确或已过期。

解决方案：

1. 访问 https://api.slack.com/apps → 选择您的应用 → “OAuth & 权限”
2. 复制当前的“机器人用户OAuth令牌”
3. 更新你的 .env 文件或Claude Desktop配置
4. 重启MCP服务器

速率限制

原因： Slack API有速率限制（第三层级：每分钟50+次请求）。

解决方案：

• 在快速请求之间添加延迟
• 对于大数据集，使用分页参数（limit，cursor）
• 在错误消息中监控速率限制头部信息

MCP 检查器无法启动

原因： 端口已被使用或 Node.js 存在问题。

解决方案：

# Kill any existing inspector processes
pkill -f "mcp.*inspector"

# Try again
npx @modelcontextprotocol/inspector node build/index.js

寻求帮助

如果你还是卡住了：

1. 检查构建输出： 跑 npm run build 并查找 TypeScript 错误
2. 验证节点版本： 跑 node --version （需18岁以上）
3. 手动测试代币： 请使用Slack的API测试工具，网址为：https://api.slack.com/methods/auth.test/test
4. 启用调试日志记录： 设定 DEBUG=* 环境变量

仍然有问题吗？请在（相关平台/系统）提交一个问题 与；带有；和

• 错误信息（全文）
• 您的 Node.js 版本
• 复现步骤

发展

建筑

npm run build

在开发中运行

npm run dev

使用MCP Inspector进行测试

npx @modelcontextprotocol/inspector node build/index.js

许可证

ISC（Internet Service Provider，互联网服务提供商）

做出贡献

欢迎贡献！请随时提交拉取请求。

致谢

从Python实现移植而来：https://github.com/piekstra/slack-mcp-server