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分钟)
克隆仓库并安装依赖项:```bash
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
1. 点击 **“创建新应用”** → **“从零开始”**
1. 输入应用名称(例如,“MCP Bot”)并选择您的工作区
1. 点击 **“创建应用”**
#### 2.2 配置OAuth范围
范围 · 目的 · 使用者
`channels:read` · 查看基本频道信息 · list_channels, get_channel_info
`channels:write` · 创建频道 · create_channel
`channels:manage` · 存档频道,邀请用户 · archive_channel, invite_to_channel
`users:read` · 查看用户资料 · 列出用户列表,获取用户信息
`chat:write` · 发送和更新消息 · send_message, update_message, delete_message
`files:write` · 将文件上传到Slack · upload_file
`reactions:write` 添加/删除表情符号反应 · add_reaction, remove_reaction
`team:read` · 获取工作区信息 · get_team_info
`search:read` · 搜索消息 · search_messages
> **💡 提示:** 每个作用域对于特定工具的功能运行都是必需的。缺少作用域将导致“missing_scope”错误。
#### 2.3 安装到工作区
1. 滚动到 **“为您的工作区提供的OAuth令牌”**
1. 点击 **“安装到工作区”**
1. 检查权限并点击 **“允许”**
#### 2.4 复制您的机器人令牌
1. 安装后,您会看到 **“机器人用户OAuth令牌”**
1. 点击 **“复制”** (令牌以...开始 `xoxb-`)
1. 请妥善保管这个令牌——下一步会需要用到它
**✓ 验证:** 您的令牌应该看起来像这样: `xoxb---`
______________________________________________________________________
### 步骤3:配置环境(2分钟)
创建您的环境配置:```bash
# Copy the example file
cp .env.example .env
编辑 .env 并添加您的机器人令牌:```bash
SLACK_BOT_TOKEN=xoxb-your-actual-token-here
**✓ 验证:** 运行此命令以确认您的令牌已加载:```bash
node -e "require('dotenv').config(); console.log('Token loaded:', !!process.env.SLACK_BOT_TOKEN)"
你应该看到: Token loaded: true
> ⚠️ 常见问题: 确保你的令牌以……开头 xoxb- (不是 xoxp- 或者 xoxa-)
步骤4:构建并验证(3分钟)
构建TypeScript项目:```bash
npm run build
**✓ 验证:** 确认 `build/` 目录已创建:```bash
ls build/index.js
你应该能看到编译后的结果 index.js 文件。
测试您的设置
在与Claude Desktop集成之前,请测试确保一切正常运行:
使用MCP Inspector
MCP Inspector 提供了一个图形用户界面 (GUI) 来测试您的工具:```bash
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仓库运行:```json
{
"mcpServers": {
"slack": {
"command": "npx",
"args": [
"github:Hais/slack-bot-mcp"
],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token-here"
}
}
}
}
好处:
- ✓ 无需本地安装
- ✓ 始终使用最新版本
- ✓ 更简单的配置
- ✓ 在任何安装了Node.js的机器上都能运行
选项2:本地安装
用于本地开发或离线使用:```json
{
"mcpServers": {
"slack": {
"command": "node",
"args": ["/absolute/path/to/slack-bot-mcp/build/index.js"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-token-here"
}
}
}
}
**本地安装设置:**
1. 克隆并构建项目(参见 安装与设置)
1. 替换 `/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客户端集成:```bash
node build/index.js
开发模式
对于支持热重载的开发:```bash
npm run dev
## 工具示例
### 列出频道```json
{
"name": "list_channels",
"arguments": {
"types": "public_channel,private_channel",
"exclude_archived": true,
"limit": 50
}
}
发送消息```json
{
"name": "send_message",
"arguments": {
"channel": "C1234567890",
"text": "Hello from MCP!"
}
}
### 使用 Block Kit 发送格式化消息```json
{
"name": "send_formatted_message",
"arguments": {
"channel": "C1234567890",
"text": "Fallback text",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Hello* from MCP with _formatting_!"
}
}
]
}
}
搜索消息```json
{
"name": "search_messages",
"arguments": {
"query": "important announcement",
"count": 10,
"sort": "timestamp"
}
}
### 上传文件```json
{
"name": "upload_file",
"arguments": {
"channels": ["C1234567890"],
"content": "File content here",
"filename": "report.txt",
"title": "Monthly Report"
}
}
添加反应```json
{
"name": "add_reaction",
"arguments": {
"channel": "C1234567890",
"timestamp": "1234567890.123456",
"name": "thumbsup"
}
}
## 所需的OAuth范围
确保您的Slack应用拥有这些权限范围:
| 范围 | 目的 |
|-------|---------|
| `channels:read` | 列出并获取频道信息 |
| `channels:write` | 创建频道 |
| `channels:manage` | 存档频道 |
| `users:read` | 列出并获取用户信息 |
| `chat:write` 发送、更新和删除消息
`files:write` · 上传文件
`reactions:write` · 添加和移除反应
`team:read` · 获取工作区信息
`search:read` · 搜索消息
## 项目结构```
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 环境变量”
原因: 服务器找不到您的机器人令牌。
解决方案:
- 验证
.env文件存在于项目根目录中:ls -la .env - 检查令牌格式:
cat .env(应显示SLACK_BOT_TOKEN=xoxb-...) - 如果使用Claude桌面配置,请确保令牌已放置在
env部分;章节 - 更改后请重启您的MCP客户端
“缺少必需的OAuth作用域”
原因: 您的机器人令牌没有必要的权限。
解决方案:
- 访问 https://api.slack.com/apps → 选择您的应用 → “OAuth & 权限”
- 添加缺失的作用域(错误信息会指明是哪一个)
- 点击“重新安装到工作区”(在添加作用域后必须执行此操作)
- 复制新的机器人令牌并更新您的配置
> 💡 注: 更改范围后,您必须重新安装应用程序。旧的令牌不会自动获得新权限。
运行时问题
“频道未找到”或“用户未找到”
原因: 你正在使用频道/用户名而不是ID。
解决方案:
- 频道ID以...开头
C(公开),G(私人),或D(直接邮件) - 用户ID以……开头
U - 使用
list_channels或者list_users用于查找正确ID的工具
示例:```json
// ❌ Wrong
{"channel": "general"}
// ✓ Correct
{"channel": "C1234567890"}
#### “无效的授权”或“令牌被撤销”
**原因:** 机器人令牌不正确或已过期。
**解决方案:**
1. 访问 https://api.slack.com/apps → 选择您的应用 → “OAuth & 权限”
1. 复制当前的“机器人用户OAuth令牌”
1. 更新你的 `.env` 文件或Claude Desktop配置
1. 重启MCP服务器
#### 速率限制
**原因:** Slack API有速率限制(第三层级:每分钟50+次请求)。
**解决方案:**
- 在快速请求之间添加延迟
- 对于大数据集,使用分页参数(limit,cursor)
- 在错误消息中监控速率限制头部信息
#### MCP 检查器无法启动
**原因:** 端口已被使用或 Node.js 存在问题。
**解决方案:**```bash
# Kill any existing inspector processes
pkill -f "mcp.*inspector"
# Try again
npx @modelcontextprotocol/inspector node build/index.js
寻求帮助
如果你还是卡住了:
- 检查构建输出: 跑
npm run build并查找 TypeScript 错误 - 验证节点版本: 跑
node --version(需18岁以上) - 手动测试代币: 请使用Slack的API测试工具,网址为:https://api.slack.com/methods/auth.test/test
- 启用调试日志记录: 设定
DEBUG=*环境变量
仍然有问题吗?请在(相关平台/系统)提交一个问题 GitHub 仓库 与;带有;和
- 错误信息(全文)
- 您的 Node.js 版本
- 复现步骤
发展
建筑```bash
npm run build
### 在开发中运行```bash
npm run dev
使用MCP Inspector进行测试```bash
npx @modelcontextprotocol/inspector node build/index.js
```
许可证
ISC(Internet Service Provider,互联网服务提供商)
做出贡献
欢迎贡献!请随时提交拉取请求。
致谢
从Python实现移植而来:https://github.com/piekstra/slack-mcp-server
