MCP Slack Lists

🚀 Slack Lists MCP 服务器

这是一个生产就绪的模型上下文协议（MCP）服务器，它为 AI 助手提供了与 Slack 列表进行交互的强大工具。该服务器充当 AI 模型和 Slack 之间的桥梁，通过标准化协议实现 Slack 列表项的无缝创建、检索、过滤和管理。它使 Claude Desktop 等 AI 助手成为在 Slack 中管理任务、项目和数据的强大生产力工具。

本项目提供了一个完整的、可用于生产环境的软件包，具备以下特点：

• 全面的工具集：可以创建、查询、过滤和导出列表项。
• 稳健的实现：使用 Python、FastMCP 构建，并遵循最佳实践。
• 易于部署：通过环境变量即可简单设置。
• 详细的文档：包含完整的 README、工具参考和示例。
• 可扩展的设计：可以轻松添加新工具和功能。

无论你是想将 AI 与 Slack 集成的开发者，还是希望提升生产力的用户，这个 MCP 服务器都为与 Slack 列表进行强大的上下文感知交互奠定了基础。

✨ 主要特性

这个 MCP 服务器提供了一组丰富的工具，用于与 Slack 列表进行交互：

• 创建单个项目：将一个带有详细字段的项目添加到列表中。
• 批量创建项目：一次性添加多个项目，并内置了速率限制，以遵守 Slack 的 API 规则。
• 检索项目：获取项目列表，并可选择包含元数据。
• 过滤项目：基于任何字段值（状态、负责人、优先级等）进行强大的服务器端过滤。
• 导出数据：将列表项目导出为 JSON 或 CSV 格式，以便进行分析或备份。
• 创建子任务：在父项目下创建子项目。
• 全字段支持：支持所有 Slack 列表字段类型（文本、日期、用户、选择、复选框等）。
• 错误处理：强大的错误处理机制，并为失败的操作提供清晰的反馈。
• 生产就绪：包含日志记录、基于环境的配置和清晰的项目结构。

🚀 快速开始

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

前提条件

• Python 3.10+
• Slack 工作区：一个你有权限安装应用的 Slack 工作区。
• Slack 机器人令牌：一个具有 lists:read 和 lists:write 权限的机器人令牌。

1. 创建 Slack 应用

1. 访问 Slack API 网站，点击 创建新应用。
2. 选择“从头开始创建”，为你的应用命名（例如“Lists MCP Server”），并选择你的工作区。
3. 在应用设置中，转到 OAuth & 权限。
4. 在 机器人令牌权限 下，添加以下权限：
   • lists:read
   • lists:write
5. 点击页面顶部的 安装到工作区，并授权该应用。
6. 复制 机器人用户 OAuth 令牌（以 xoxb- 开头）。这就是你的 SLACK_BOT_TOKEN。

2. 安装

克隆仓库并安装依赖项：

# 克隆仓库
git clone https://github.com/your-org/slack-lists-mcp-server.git
cd slack-lists-mcp-server

# 创建并激活虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装依赖项
pip install -r requirements.txt

3. 配置

通过复制示例文件创建 .env 文件：

cp .env.example .env

打开 .env 文件，设置你的 SLACK_BOT_TOKEN：

SLACK_BOT_TOKEN=xoxb-your-bot-token-here

4. 运行服务器

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

python src/slack_lists_server.py

服务器将启动并通过标准输入输出监听 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 可执行文件和服务器脚本的绝对路径。

配置完成后，重启你的 MCP 主机。现在，Slack 列表工具应该可供你的 AI 助手使用。

📚 详细文档

工具参考

此服务器向你的 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 中创建一个新任务，标题为 '完成第四季度报告'，截止日期为 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 文件。"

数据格式

字段格式

在使用 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": "第一个任务",
    "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 错误：使用在线验证器验证你的 additional_fields 和 items_data 的 JSON 字符串。

如何查找列表和列 ID

1. 列表 ID：在 Slack 中打开列表。ID 是 URL 的最后一部分（例如 https://app.slack.com/client/.../F1234ABCD）。
2. 列 ID：你可以通过在浏览器的开发者工具中检查与列表交互时的网络请求来查找列 ID，或者使用 get_list_items 工具并检查输出。

贡献

欢迎贡献！如果你有新功能、错误修复或改进的想法，请打开一个问题或提交一个拉取请求。更多详细信息请参阅 CONTRIBUTING.md。

📄 许可证

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