内容
# Slack 列表 MCP 服务器
<!-- mcp-name: io.github.justadityaraj/slack-lists-mcp -->
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
**一个 Model Context Protocol (MCP) 服务器，提供 AI 助手对 Slack 列表的完全读写访问权限。**
该服务器作为 AI 模型和 Slack 之间的桥梁，通过标准化的协议实现无缝的 Slack 列表项的创建、检索、更新、删除、过滤和管理。它使像 Claude Desktop 这样的 AI 助手成为管理 Slack 中任务、项目和数据的强大生产力工具。
该项目提供了一个完整的软件包，包括：
- **全面的工具集**：创建、查询、更新、删除、过滤和导出列表项。
- **稳健的实现**：使用 Python、FastMCP 和最佳实践构建。
- **简单的部署**：使用环境变量进行简单的设置。
- **详细的文档**：完整的 README、工具参考和示例。
- **可扩展的设计**：可以轻松添加新的工具和功能。
已验证的写入路径针对实时 Slack 工作区（参见 [验证状态](#验证状态)）。
## 功能
该 MCP 服务器为与 Slack 列表交互提供了一套丰富的工具：
- **创建单个项**：将一个项添加到列表中，包含详细的字段。
- **批量创建项**：一次添加多个项，内置速率限制以尊重 Slack 的 API。
- **检索项**：获取列表项的可选元数据。
- **更新项**：更新现有项的任何单元格 - 标记任务完成、重新分配、重新安排或编辑任何字段（完整的任务管理）。
- **删除项**：永久从列表中删除项。
- **发现列**：从现有项中推断列表的列 ID、类型和选择选项 ID（Slack 没有公开的架构 API，因此可以节省您在浏览器开发工具中查找 ID 的时间）。
- **过滤项**：基于任何字段值的强大的服务器端过滤（状态、分配者、优先级等）。
- **导出数据**：将列表项导出为 JSON 或 CSV 格式进行分析或备份。
- **子任务创建**：在父项下创建子项。
- **完整的字段支持**：适用于所有 Slack 列表字段类型（文本、日期、用户、选择、复选框、数字、电子邮件、电话）。
- **错误处理**：强大的错误处理和清晰的失败操作反馈。
## 入门指南
按照以下步骤启动并运行您的 Slack 列表 MCP 服务器。
### 先决条件
- **Python 3.10+**
- **Slack 工作区**：您具有安装应用权限的 Slack 工作区。
- **Slack 机器人令牌**：具有 `lists:read` 和 `lists:write` 范围的机器人令牌。
### 1. 创建 Slack 应用
1. 访问 [Slack API 网站](https://api.slack.com/apps) 并点击 **创建新应用**。
2. 选择“从头开始”，输入应用名称（例如“列表 MCP 服务器”），并选择您的工作区。
3. 在应用设置中，转到 **OAuth 和权限**。
4. 在 **机器人令牌范围** 下，添加以下范围：
- `lists:read`
- `lists:write`
5. 点击页面顶部的 **安装到工作区** 并授权应用。
6. 复制 **机器人用户 OAuth 令牌**（以 `xoxb-` 开头）。这是您的 `SLACK_BOT_TOKEN`。
### 2. 安装
克隆存储库并安装依赖项：
```bash
# 克隆存储库
git clone https://github.com/justadityaraj/slack-lists-mcp.git
cd slack-lists-mcp
# 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖项
pip install -r requirements.txt
```
### 3. 配置
通过复制示例创建 `.env` 文件：
```bash
cp .env.example .env
```
打开 `.env` 文件并设置您的 `SLACK_BOT_TOKEN`：
```dotenv
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
```
服务器在启动时会自动加载此 `.env` 文件（从项目根目录），因此您不需要将令牌放在其他地方。实际的 `SLACK_BOT_TOKEN` 环境变量始终优先于文件。
### 4. 运行服务器
您可以直接从命令行运行服务器：
```bash
python src/slack_lists_server.py
```
服务器将启动并通过 STDIO 监听 MCP 请求。
### 5. 连接到 MCP 主机（例如 Claude Desktop）
要将服务器与 AI 助手一起使用，您需要配置您的 MCP 主机。
1. 打开您的 MCP 主机的配置文件（例如 Claude Desktop 的 `mcp_servers.json`）。
2. 添加一个新的服务器条目，指向您的 `slack_lists_server.py` 脚本。
**`mcp_servers.json` 配置示例：**
```json
{
"mcpServers": {
"slack-lists": {
"command": "/path/to/your/.venv/bin/python",
"args": ["/path/to/slack-lists-mcp-server/src/slack_lists_server.py"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-bot-token-here"
}
}
}
}
```
**重要**：确保使用 Python 可执行文件和服务器脚本的绝对路径。因为服务器从 `.env` 文件中读取令牌，所以上面的 `env` 块是可选的。
配置完成后，重启您的 MCP 主机。Slack 列表工具现在应该可用于您的 AI 助手。
#### Claude 代码（CLI）
```bash
claude mcp add slack-lists -s user -- /abs/path/.venv/bin/python /abs/path/slack-lists-mcp/src/slack_lists_server.py
```
不需要 `-e SLACK_BOT_TOKEN=...`；服务器从 `.env` 文件中获取令牌。
## 工具参考
该服务器向您的 AI 助手公开以下工具。每个工具都设计为直观且强大，具有清晰的描述和参数。
---
### `create_list_item`
在 Slack 列表中创建单个新项。
**描述：**
该工具在指定的 Slack 列表中创建一个项。该项必须至少有一个标题字段，也可以包含其他字段。所有字段值都将根据列表的架构进行验证。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID（例如 `F1234ABCD`）。
- `title`（字符串，必填）：项的主要标题/文本。
- `title_column_id`（字符串，可选）：标题字段的列 ID（默认为 `Col10000000`）。
- `additional_fields`（字符串，可选）：附加字段的 JSON 字符串。有关详细信息，请参见 [字段格式](#字段格式)。
- `parent_item_id`（字符串，可选）：可选的父项 ID，用于创建子任务。
**示例提示：**
> “在我的项目列表 `F1234ABCD` 中创建一个新任务，标题为 '完成 Q4 报告'，截止日期为 2024-12-20。”
---
### `create_multiple_list_items`
在 Slack 列表中创建多个项，带有速率限制。
**描述：**
该工具允许批量创建列表项。每个项都是单独创建的，带有适当的速率限制，以尊重 Slack 的 API 限制（每分钟约 50 个请求）。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID。
- `items_data`（字符串，必填）：要创建的项的 JSON 数组。有关详细信息，请参见 [批量创建格式](#批量创建格式)。
- `title_column_id`（字符串，可选）：标题字段的列 ID。
- `rate_limit_delay`（浮点数，可选）：请求之间的延迟（秒）（默认：1.2 秒）。
**示例提示：**
> “在我的列表 `F1234ABCD` 中添加以下三个任务：1. 设计模型（截止日期 12/10），2. 编写测试（截止日期 12/15），3. 更新文档（截止日期 12/20）。"
---
### `get_list_items`
从 Slack 列表中检索项。
**描述：**
该工具从指定的 Slack 列表中获取项，并带有可选的元数据。使用此工具查看当前列表内容、检查项详细信息或准备数据进行过滤。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID。
- `limit`（整数，可选）：要检索的最大项数（默认：50，最大：100）。
- `include_metadata`（布尔值，可选）：是否包含创建时间/更新元数据（默认：True）。
**示例提示：**
> “显示我的 '任务' 列表 `F5678EFGH` 中最近的 10 个项。”
---
### `filter_list_items`
根据字段值过滤和检索 Slack 列表中的项。
**描述：**
该工具允许您按特定字段值搜索和过滤列表项。适用于查找具有特定状态、分配者、优先级或其他任何字段的项。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID。
- `filter_column_id`（字符串，必填）：要过滤的列 ID。
- `filter_value`（字符串，必填）：要搜索的值。
- `filter_operator`（字符串，可选）：如何匹配值。有关选项，请参见 [过滤运算符](#过滤运算符)。
- `max_items`（整数，可选）：要处理的最多项数（默认：100）。
**示例提示：**
> “在列表 `F1234ABCD` 中查找所有分配给我且优先级标记为 '高' 的任务。”
---
### `export_list_items`
将 Slack 列表中的项导出为结构化数据格式。
**描述：**
该工具将列表项导出为 JSON 或 CSV 格式，并带有可选的过滤。适用于备份、分析或与其他系统集成。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID。
- `export_format`（字符串，可选）：输出格式 - `json` 或 `csv`（默认：`json`）。
- `filter_column_id`（字符串，可选）：可选的过滤列 ID。
- `filter_value`（字符串，可选）：过滤值（如果提供了 `filter_column_id`，则必填）。
- `filter_operator`（字符串，可选）：过滤运算符。
**示例提示：**
> “将我的项目列表 `F1234ABCD` 中的所有已完成任务导出到 CSV 文件中。”
---
### `update_list_item`
更新 Slack 列表中现有项的一个或多个单元格（行）。此工具用于完全的任务管理：标记任务完成、重新分配、重新安排或编辑任何字段 - 只需一次调用。
**描述：**
更新 `row_id` 标识的项上的给定列。查找 `row_id` 使用 `get_list_items` 或 `filter_list_items`（它是每个项的 `id`，例如 `Rec1234567`）。查找 `column_id`s 和选择选项 ID 使用 `discover_list_columns`。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID（例如 `F1234ABCD`）。
- `row_id`（字符串，必填）：要更新的项/行的 ID（例如 `Rec1234567`）。
- `fields`（字符串，必填）：要更新的单元格的 JSON 数组。每个单元格为 `{"column_id": "...", "type": "...", "value": ...}`。有关详细信息，请参见 [字段格式](#字段格式)。支持的类型：`text`、`date`、`user`、`select`、`checkbox`、`number`、`email`、`phone`。
**示例提示：**
> “将列表 `F1234ABCD` 中的任务 `Rec1234567` 标记为完成，重新分配给 `U1234567`，并将截止日期改为 2025-09-20。”
---
### `delete_list_item`
永久删除 Slack 列表中的项（行）。此操作无法撤销。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID（例如 `F1234ABCD`）。
- `row_id`（字符串，必填）：要删除的项/行的 ID（例如 `Rec1234567`）。
**示例提示：**
> “从列表 `F1234ABCD` 中删除项 `Rec1234567`。”
---
### `discover_list_columns`
通过检查现有项来发现列表的列。Slack 没有直接读取列表架构的 API，因此这可以推断每个列的 ID、类型、示例值和（对于选择列）选项 ID。
**注意：** 只有至少一个项在其中具有值，列才可被发现。空列不会出现。
**参数：**
- `list_id`（字符串，必填）：Slack 列表的 ID（例如 `F1234ABCD`）。
- `sample_size`（整数，可选）：要扫描的项数，1-1000（默认：100）。
**示例提示：**
> “列表 `F1234ABCD` 有哪些列，状态选项 ID 是什么？”
## 数据格式
### 字段格式
使用 `create_list_item` 或 `create_multiple_list_items` 时，您需要以特定的 JSON 格式提供字段数据。`additional_fields` 和 `items_data` 参数期望一个 JSON 字符串。
每个字段是一个具有 `column_id`、`type` 和 `value` 的对象：
```json
[
{
"column_id": "Col10000001",
"type": "date",
"value": "2024-12-31"
},
{
"column_id": "Col10000002",
"type": "select",
"value": ["OptionID123"]
},
{
"column_id": "Col10000003",
"type": "user",
"value": ["U1234567", "U2345678"]
},
{
"column_id": "Col10000004",
"type": "checkbox",
"value": true
}
]
```
**支持的字段类型：**
- `text`：字符串值。
- `date`：`YYYY-MM-DD` 格式的字符串。
- `user`：Slack 用户 ID 数组（例如 `["U1234567"]`）。
- `select`：选择选项 ID 数组。
- `checkbox`：布尔值 `true` 或 `false`。
- `number`：数值。
- `email`：字符串电子邮件地址。
- `phone`：字符串电话号码。
### 批量创建格式
`create_multiple_list_items` 的 `items_data` 参数期望一个 JSON 数组，其中每个对象表示要创建的项。
```json
[
{
"title": "第一个任务",
"fields": [
{"column_id": "Col123", "type": "date", "value": "2024-12-15"}
]
},
{
"title": "第二个任务",
"fields": [
{"column_id": "Col123", "type": "date", "value": "2024-12-20"},
{"column_id": "Col456", "type": "user", "value": ["U1234567"]}
]
}
]
```
### 过滤运算符
`filter_list_items` 工具支持以下运算符：
- `contains`：字段包含值（不区分大小写）。
- `equals`：字段完全匹配值（不区分大小写）。
- `not_equals`：字段不匹配值。
- `not_contains`：字段不包含值。
- `exists`：字段具有任何非空值。
- `not_exists`：字段为空或缺失。
## 故障排除
- **`invalid_auth` 错误**：您的 `SLACK_BOT_TOKEN` 可能不正确或已撤销。生成一个新的并更新您的 `.env` 文件。
- **`missing_scope` 错误**：确保您的 Slack 应用具有 `lists:read` 和 `lists:write` 范围。
- **`list_not_found` 错误**：您提供的 `list_id` 不正确。在 Slack 中再次检查 ID。
- **服务器无响应**：确保服务器正在运行，并且您的 MCP 主机配置中的路径正确。检查服务器日志中的任何错误。
- **JSON 错误**：使用在线验证器验证您的 JSON 字符串的 `additional_fields` 和 `items_data`。
## 如何查找列表和列 ID
1. **列表 ID**：在 Slack 中打开列表。ID 是 URL 的最后一部分（例如 `https://app.slack.com/client/.../F1234ABCD`）。
2. **列 ID**：最简单的方法是使用 `discover_list_columns` 工具，该工具通过检查列表的现有项来列出每个列的 ID、类型和选择选项 ID。（您也可以检查浏览器的网络请求，或读取 `get_list_items` 的原始输出。）
## 贡献
欢迎贡献！如果您有新功能、错误修复或改进的想法，请打开一个问题或提交一个拉取请求。有关更多详细信息，请参见 `CONTRIBUTING.md`。
## 验证状态
所有工具都涵盖了单元测试，并且已经针对实时 Slack 工作区进行了测试：`discover_list_columns`、`create_list_item`、`update_list_item`（文本、用户、日期和复选框单元格，包括单个多单元格“标记完成 + 重新分配 + 重新安排”更新）和 `delete_list_item` 都正确地完成了往返。
一个字段形状与已发布的文档不同：**复选框单元格采用裸布尔值**（`"checkbox": true`），而不是数组。文档显示 `"checkbox": [boolean]`，但实时 API 拒绝数组形式并返回值为裸布尔值，因此该服务器发送裸布尔值。
## 致谢
该项目源自 [maplehilllabs/mcp-slack-lists](https://github.com/maplehilllabs/mcp-slack-lists)（MIT），扩展了 `update_list_item`、`delete_list_item` 和 `discover_list_columns` 以及完整的字段类型支持。
## 许可证
该项目在 MIT 许可证下获得许可。有关详细信息，请参见 [LICENSE](LICENSE) 文件。
<!-- 作者：[Aditya Raj Singh](https://adityarajsingh.com/) -->
