slack-lists-mcp

Slack Lists MCP 服务

一个 Model Context Protocol（MCP）服务，为 AI 助手提供对 Slack Lists 的完整读写权限。

此服务充当 AI 模型与 Slack 之间的桥梁，通过标准化协议，实现 Slack List 条目的无缝创建、检索、更新、删除、筛选和管理。它让 Claude Desktop 等 AI 助手成为强大的效率工具，帮助用户在 Slack 中管理任务、项目和数据。

本项目提供完整的功能包，包括：

• 全面的工具集：创建、查询、更新、删除、筛选和导出列表条目。
• 可靠的实现：基于 Python、FastMCP 和最佳实践构建。
• 轻松部署：通过环境变量即可简单配置。
• 详尽的文档：完整的 README、工具参考和示例。
• 可扩展的设计：轻松添加新工具和功能。

写入功能已在实际 Slack 工作区中验证（参见验证状态）。

功能

此 MCP 服务提供丰富的工具，用于与 Slack Lists 交互：

• 创建单个条目：向列表添加一个包含详细字段的条目。
• 批量创建条目：一次添加多个条目，并内置速率限制以符合 Slack API 的要求。
• 检索条目：获取条目列表，可选择包含元数据。
• 更新条目：更新现有条目的任意单元格——勾选任务、重新指派负责人、调整安排，或编辑任何字段（完整的任务管理）。
• 删除条目：从列表中永久移除条目。
• 发现列：根据列表现有条目推断列 ID、类型和选项 ID（Slack 不提供架构 API，因此无需再从浏览器开发者工具中费力查找 ID）。
• 筛选条目：根据任意字段值（状态、负责人、优先级等）进行强大的服务端筛选。
• 导出数据：将列表条目导出为 JSON 或 CSV 格式，用于分析或备份。
• 创建子任务：在父条目下创建子条目。
• 全面的字段支持：支持所有 Slack List 字段类型（文本、日期、用户、选择框、复选框、数字、电子邮件、电话）。
• 错误处理：提供可靠的错误处理，并清晰反馈操作失败的原因。

开始使用

按照以下步骤启动并运行 Slack Lists MCP 服务。

前提条件

• Python 3.10+
• Slack 工作区：你有权限安装应用的 Slack 工作区。
• Slack Bot 令牌：具有 lists:read 和 lists:write 权限范围的 Bot 令牌。

1. 创建 Slack 应用

1. 前往 Slack API 网站，点击 Create New App。
2. 选择 "From scratch"，为应用命名（例如 "Lists MCP Server"），并选择你的工作区。
3. 在应用设置中，前往 OAuth & Permissions。
4. 在 Bot Token Scopes 下添加以下权限范围：
   • lists:read
   • lists:write
5. 点击页面顶部的 Install to Workspace，并授权该应用。
6. 复制 Bot User OAuth Token（以 xoxb- 开头）。这就是你的 SLACK_BOT_TOKEN。

2. 安装

克隆代码库并安装依赖项：

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

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. 配置

复制示例文件，创建 .env 文件：

cp .env.example .env

打开 .env 文件并设置 SLACK_BOT_TOKEN：

SLACK_BOT_TOKEN=xoxb-your-bot-token-here

服务启动时会自动从项目根目录加载此 .env 文件，因此无需在其他位置设置令牌。实际的 SLACK_BOT_TOKEN 环境变量始终优先于文件中的值。

4. 运行服务

你可以直接从命令行运行服务：

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 配置示例：

{
  "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 Lists 工具现在应该已可供您的 AI 助手使用。

Claude Code（CLI）

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 List 中创建一个新条目。

说明： 此工具会在指定的 Slack List 中创建一个条目。条目至少必须包含标题字段，也可以根据需要包含其他字段。所有字段值都会根据列表架构进行验证。

参数：

• list_id（字符串，必填）：Slack List 的 ID（例如，F1234ABCD）。
• title（字符串，必填）：条目的主要标题/文本。
• title_column_id（字符串，可选）：标题字段的列 ID（默认为 Col10000000）。
• additional_fields（字符串，可选）：其他字段的 JSON 字符串。详情请参阅字段格式。
• parent_item_id（字符串，可选）：可选的父条目 ID，用于创建子任务。

提示词示例：

“在我的项目列表 F1234ABCD 中创建一个新任务，标题为 ‘完成第 4 季度报告’，截止日期为 2024-12-20。”

---

create_multiple_list_items

在 Slack List 中创建多个条目，并进行速率限制。

说明： 此工具支持批量创建列表条目。每个条目都会单独创建，并进行适当的速率限制，以遵守 Slack 的 API 限制（约每分钟 50 次请求）。

参数：

• list_id（字符串，必填）：Slack List 的 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 List 中获取条目。

说明： 此工具会从指定的 Slack List 中获取条目，并可选择包含元数据。可使用此工具查看列表当前内容、检查条目详情，或为筛选数据做准备。

参数：

• list_id（字符串，必填）：Slack List 的 ID。
• limit（整数，可选）：要获取的条目数上限（默认值：50，最大值：100）。
• include_metadata（布尔值，可选）：是否包含创建/更新元数据（默认值：True）。

提示词示例：

“显示我的 ‘Tasks’ 列表 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 标识的条目中的指定列。可通过 get_list_items 或 filter_list_items 查找 row_id（它是每个条目的 id，例如 Rec1234567）。可通过 discover_list_columns 查找 column_id 和选择选项 ID。

参数：

• 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。使用此工具查找 create_list_item 和 update_list_item 所需的 column_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：

[
  {
    "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 数组，其中每个对象代表一个要创建的项目。

[
  {
    "title": "First Task",
    "fields": [
      {"column_id": "Col123", "type": "date", "value": "2024-12-15"}
    ]
  },
  {
    "title": "Second Task",
    "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 错误：使用在线验证器检查 additional_fields 和 items_data 中的 JSON 字符串是否有效。

如何查找列表和列 ID

1. 列表 ID：在 Slack 中打开列表。ID 是 URL 的最后一部分（例如，https://app.slack.com/client/.../F1234ABCD）。
2. 列 ID：最简单的方法是使用 discover_list_columns 工具。该工具会检查列表中的现有项目，并列出每列的 ID、类型和选择选项 ID。（您也可以检查浏览器网络请求，或读取 get_list_items 的原始输出。）

贡献

欢迎贡献！如果您有新功能、错误修复或改进方面的想法，请提交 issue 或拉取请求。更多详情请参阅 CONTRIBUTING.md。

验证状态

所有工具都已通过单元测试，并在实际 Slack 工作区中进行了测试：discover_list_columns、create_list_item、update_list_item（文本、用户、日期和复选框单元格，包括一次同时执行“勾选 + 重新分配 + 重新安排”的多单元格更新）以及 delete_list_item 均已验证往返操作正常。

有一种字段格式与已发布的文档不同：复选框单元格需要使用独立的布尔值（"checkbox": true），而不是数组。文档中写的是 "checkbox": [boolean]，但实际 API 会拒绝数组格式并返回 invalid_arguments，且返回值是独立的布尔值，因此此服务发送独立的布尔值。

致谢

本项目基于 maplehilllabs/mcp-slack-lists（MIT）开发，并扩展了 update_list_item、delete_list_item 和 discover_list_columns，还支持所有字段类型。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。