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 文件。