使用说明

Slack MCP服务器

⚠️ 免责声明：此项目100%由人工智能编码。买家请小心！

整个代码库是通过使用Claude Code的人工智能辅助开发生成的。虽然它通过了所有质量门（Pylint 10/10、mypy strict、67项测试）、安全审计（Bandit、pip审计），并有全面的文档，但它还没有在生产环境中经过实战测试。在部署到关键系统之前，请自行承担风险并检查代码。

一种模型上下文协议（MCP）服务器，通过用户级OAuth操作为AI助手提供对Slack工作区的全面访问。支持将Slack对话、用户、文件和工作空间操作无缝集成到人工智能辅助的工作流程中。

特性

🔧 四种主题MCP工具

松弛_对话 -全面的信息和渠道运营

使用过滤器跨渠道搜索邮件
按时间顺序阅读频道的对话历史记录
阅读一个帖子中的所有回复
使用Slack标记将消息发布到频道/DM
回复维护对话上下文的线程
列出、创建和存档频道
管理渠道成员

懒鬼_用户 -工作区用户目录和配置文件

列出所有分页的工作区用户
获取详细的用户配置文件（姓名、职务、电子邮件、时区、状态）
检查用户状态/在线状态
按姓名或电子邮件搜索用户

slack_files -文档和媒体共享自动化

将文件上传到频道/DM
列出带有过滤器的文件（用户、频道、日期、类型）
获取文件元数据和下载URL
删除用户的文件

宽松的工作空间 -团队元数据和配置

获取工作区信息（名称、域、图标、计划）
列出自定义表情符号
访问工作区统计信息

✨ 核心能力

多工作区支持：通过简单的配置切换管理多个Slack工作区
用户级操作：真实的用户操作（不是机器人操作）
异步性能：所有Slack API调用的非阻塞I/O
费率限制处理：通过指数退避优雅地处理Slack API速率限制
类型安全：带有mypy严格验证的完整类型提示
安全：OAuth令牌受600个文件权限保护，从未记录或公开

安装

先决条件

Python 3.12或更高版本
诗歌1.7或更高
Slack工作区，您可以在其中创建应用程序

设置

克隆存储库

git clone https://github.com/yourusername/slack-mcp.git
cd slack-mcp

安装依赖项
```
poetry install
```
创建Slack应用程序 （参见 Slack应用程序设置在......下面
配置工作区凭据 （参见配置在......下面

Slack应用程序设置

要使用此MCP服务器，您需要创建一个Slack应用程序并生成一个用户OAuth令牌。

⚡ 快速设置（推荐）

使用我们预先配置的应用程序清单进行即时设置：

首选https://api.slack.com/apps
点击 “创建新应用程序” → “来自应用程序清单”
选择您的工作区并单击 “下一个”
从以下位置复制YAML docs/slack-manifest.md 并将其粘贴
点击 “创建” → “安装到工作区” → “允许”
复制 用户OAuth令牌 （开始于 xoxp-)

完成！ 所有必需的作用域都已预先配置。跳到配置.

📝 手动设置（替代）

如果您更喜欢手动配置：

第一步：创建Slack应用程序

首选https://api.slack.com/apps
点击 “创建新应用程序” → “从头开始”
输入应用程序名称（例如“MCP Assistant”）并选择您的工作区
点击 “创建应用程序”

步骤2：配置OAuth作用域

在您的应用程序设置中，转到 “OAuth和权限”
滚动到 “用户令牌范围” （不是Bot令牌范围）
添加以下范围：

对话：
- channels:read -查看基本频道信息
- channels:write -管理公共渠道
- channels:history -查看公共频道中的消息
- groups:read -查看基本私人频道信息
- groups:write -管理私人频道
- groups:history -查看私人频道中的消息
- im:read -查看基本DM信息
- im:write -发送DM
- im:history -查看DM消息
- mpim:read -查看组DM信息
- mpim:history -查看组DM消息
- chat:write -发布消息
用户：
- users:read -查看工作区用户
- users:read.email -查看用户电子邮件地址
文件夹：
- files:read -查看文件
- files:write -上传和管理文件
工作区：
- team:read -查看工作区信息
- emoji:read -查看自定义表情符号

步骤3：安装应用程序并生成令牌

滚动到 “工作区的OAuth令牌”
点击 “安装到工作区”
查看权限并单击 “允许”
复制 用户OAuth令牌 （开始于 xoxp-)

⚠️ 重要：这是一个用户级令牌，充当您的角色。保持安全，永远不要将其提交给git。

配置

创建配置目录

mkdir -p ~/.config/slack-mcp
chmod 700 ~/.config/slack-mcp

创建工作空间配置文件

为每个工作区创建一个JSON文件： ~/.config/slack-mcp/{workspace-name}.json

例子： ~/.config/slack-mcp/my-team.json

{
  "token": "xoxp-your-user-oauth-token-here",
  "workspace_id": "T01234567",
  "workspace_name": "My Team Workspace",
  "default": true
}

配置架构：

token （必需）：来自Slack应用程序的用户OAuth令牌（xoxp-…）
workspace_id （可选）：Slack工作区ID（T…）
workspace_name （可选）：工作区的友好名称
default （可选）：设置为 true 将其设置为默认工作区

保护您的配置

chmod 600 ~/.config/slack-mcp/*.json

这确保只有您可以读取OAuth令牌。

使用Claude代码

将MCP服务器添加到Claude代码（用户级）

将MCP服务器添加到您的用户级Claude代码配置中：

claude mcp add -s user slack-mcp -- poetry -C /absolute/path/to/slack-mcp run start-mcp

替换 /absolute/path/to/slack-mcp 使用克隆存储库的实际路径。

这将服务器添加到 ~/.config/claude/mcp.json 对于您的用户帐户。

测试服务器

重新启动Claude Code并尝试：

slack_workspace(operation='get_info')

您应该看到返回的工作区信息。

使用示例

搜索邮件

slack_conversations(
  operation='search',
  query='from:@sarah project deadline',
  channel='C01234567'
)

阅读频道历史记录

slack_conversations(
  operation='get_history',
  channel='C01234567',
  limit=100,
  oldest='1234567890.123456',  # optional: Unix timestamp
  latest='1234567900.123456',  # optional: Unix timestamp
  inclusive=False              # optional: include oldest/latest timestamps
)

阅读帖子回复

slack_conversations(
  operation='get_replies',
  channel='C01234567',
  thread_ts='1234567890.123456',
  limit=100
)

发布消息

slack_conversations(
  operation='post_message',
  channel='C01234567',
  text='Hello from AI assistant! 👋'
)

回复Thread

slack_conversations(
  operation='post_message',
  channel='C01234567',
  text='Great point!',
  thread_ts='1234567890.123456'
)

列出频道

slack_conversations(
  operation='list_channels',
  types=['public', 'private']
)

获取用户资料

slack_users(
  operation='get_user',
  user_id='U01234567'
)

上传文件

slack_files(
  operation='upload',
  file_path='/path/to/document.pdf',
  channels=['C01234567'],
  title='Meeting Notes',
  initial_comment='Notes from today\'s sync'
)

列出文件

slack_files(
  operation='list_files',
  channel='C01234567',
  types=['pdfs', 'images'],
  limit=20
)

获取文件信息

slack_files(
  operation='get_file_info',
  file_id='F01234567'
)

删除文件

slack_files(
  operation='delete_file',
  file_id='F01234567'
)

获取工作区信息

slack_workspace(
  operation='get_team_info'
)

列出自定义表情符号

slack_workspace(
  operation='list_emoji'
)

获取工作区统计信息

slack_workspace(
  operation='get_stats'
)

列出所有工作区

slack_workspace(
  operation='list_workspaces'
)

切换工作空间

slack_workspace(
  operation='switch_workspace',
  workspace_name='other-team'
)

获取活动工作区

slack_workspace(
  operation='get_active_workspace'
)

发展

设置开发环境

# Install dependencies including dev tools
poetry install

# Activate virtual environment
poetry shell

运行测试

# Run all tests with coverage
poetry run pytest --cov=slack_mcp

# Run specific test file
poetry run pytest tests/test_mcp_server.py

# Run with verbose output
poetry run pytest -v

代码质量检查

# Linting (target: 10.00/10)
poetry run pylint slack_mcp

# Type checking
poetry run mypy slack_mcp --strict

# Security scanning
poetry run bandit -r slack_mcp

# Dependency audit
poetry run pip-audit

# Code formatting
poetry run black slack_mcp

在本地运行MCP服务器

# Run with Poetry
poetry run start-mcp

# Or directly with Python
poetry run python -m slack_mcp

# With debug logging
poetry run python -m slack_mcp --debug

使用MCP检查员进行测试

# Install MCP Inspector (if not already installed)
npm install -g @modelcontextprotocol/inspector

# Test the MCP server
mcp-inspector poetry -C /path/to/slack-mcp run start-mcp

项目结构

slack-mcp/
├── slack_mcp/
│   ├── __init__.py              # Package metadata
│   ├── __main__.py              # Entry point with run_main()
│   ├── server.py                # STDIO server setup with signal handlers
│   ├── mcp_server.py            # MCP server class and tool registration
│   ├── config.py                # Configuration management
│   ├── workspace_manager.py    # Multi-workspace configuration
│   ├── slack_client.py          # Slack API client wrapper
│   ├── conversations_manager.py # Conversations operations
│   ├── users_manager.py         # User operations
│   ├── files_manager.py         # File operations
│   └── workspace_operations.py # Workspace operations
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # Pytest fixtures
│   ├── test_mcp_server.py
│   ├── test_config.py
│   ├── test_workspace_manager.py
│   └── ...
├── docs/
│   ├── project-charter.md
│   ├── requirements.md
│   ├── functional-requirements.md
│   └── implementation.md
├── pyproject.toml               # Poetry configuration
├── poetry.lock                  # Dependency lock file
├── AGENTS.md                    # AI agent development guidelines
└── README.md                    # This file

故障排除

OAuth令牌问题

错误：“invalid_auth”或“token_revoked”

您的OAuth令牌可能已过期或被吊销
从Slack应用程序设置生成新的用户OAuth令牌
更新工作区配置文件中的令牌

错误：“missing_scope”

您的令牌没有所需的OAuth作用域
转到Slack应用程序的“OAuth和权限”页面
在“用户令牌作用域”下添加缺失的作用域
将应用程序重新安装到您的工作区
将新令牌复制到配置文件中

配置问题

错误：“找不到配置”

确保 ~/.config/slack-mcp/{workspace}.json 存在
检查工作区名称是否与您尝试使用的名称匹配

错误：“配置必须具有600个权限”

运行： chmod 600 ~/.config/slack-mcp/*.json

速率限制

错误：“rate_limited”或HTTP 429

Slack API有速率限制（第3层：约1个请求/秒，第4层：约100个请求/分钟）
服务器自动实现指数回退
如果您经常看到这种情况，请降低API调用频率

MCP连接问题

克劳德代码中未显示服务器

验证中的路径 claude mcp add 命令是绝对正确的
检查Poetry是否已安装且可访问
尝试重新启动Claude Code
检查克劳德代码日志中的错误消息

安全注意事项

OAuth令牌保护

✅ 永远不要将代币提交给git -配置文件位于.gitignore中
✅ 使用600个文件权限 -只有您的用户可以读取配置文件
✅ 令牌从不被记录 -服务器从所有日志中排除令牌
✅ 无令牌缓存 -为每个会话加载新的令牌

数据隐私

✅ 无本地存储 -所有Slack数据都是传递的（无缓存）
✅ 尊重用户权限 -只能访问您的Slack帐户可以访问的内容
✅ 仅限STDIO传输 -无网络暴露（本地运行）

最佳实践

定期查看Slack应用程序的OAuth作用域（删除未使用的作用域）
定期轮换OAuth令牌
在工作区管理面板中监控Slack应用程序的使用情况
为不同目的使用单独的Slack应用程序（不是共享令牌）

贡献

欢迎投稿！请遵循以下指南：

阅读 AGENTS.md 开发标准
确保所有测试通过： poetry run pytest
保持10.00/10皮林分数： poetry run pylint slack_mcp
添加新功能测试（要求覆盖率≥80%）
根据需要更新文档

许可证

[在此处指定您的许可证]

致谢

建于模型上下文协议
用途 Slack Python SDK
受...启发吉拉mcp 多工作空间模式

🤖 生成于克劳德代码