MCP Slack Lists

🚀 Slack Lists MCP Server

このサーバーは、AIアシスタントがSlack Listsとやり取りするための強力なツールを提供する、本番環境で使用可能なModel Context Protocol (MCP)サーバーです。

このサーバーは、AIモデルとSlackの間の架け橋として機能し、標準化されたプロトコルを通じて、Slack Listの項目の作成、取得、フィルタリング、管理をシームレスに行えるようにします。Claude DesktopなどのAIアシスタントを、Slack内でタスク、プロジェクト、データを管理するための強力な生産性ツールに変えます。

このプロジェクトは、以下のような完全な本番環境向けのパッケージを提供します。

• 包括的なツールセット：リスト項目の作成、クエリ、フィルタリング、エクスポートが可能です。
• 堅牢な実装：Python、FastMCPを使用し、ベストプラクティスに基づいて構築されています。
• 簡単なデプロイ：環境変数を使用したシンプルなセットアップです。
• 詳細なドキュメント：完全なREADME、ツールリファレンス、サンプルが用意されています。
• 拡張可能な設計：新しいツールや機能を簡単に追加できます。

開発者がAIとSlackを統合したい場合でも、ユーザーが生産性を大幅に向上させたい場合でも、このMCPサーバーは、Slack Listsとの強力でコンテキストを認識したやり取りの基礎を提供します。

🚀 クイックスタート

以下の手順に従って、Slack Lists MCPサーバーを起動しましょう。

前提条件

• Python 3.10+
• Slackワークスペース：アプリをインストールする権限があるSlackワークスペースが必要です。
• Slackボットトークン：lists:readとlists:writeのスコープを持つボットトークンが必要です。

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. インストール

リポジトリをクローンし、依存関係をインストールします。

# リポジトリをクローンする
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.exampleをコピーして.envファイルを作成します。

cp .env.example .env

.envファイルを開き、SLACK_BOT_TOKENを設定します。

SLACK_BOT_TOKEN=xoxb-your-bot-token-here

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実行ファイルとサーバースクリプトの絶対パスを使用するようにしてください。

設定が完了したら、MCPホストを再起動します。Slack ListsのツールがAIアシスタントで使用可能になります。

✨ 主な機能

このMCPサーバーは、Slack Listsとやり取りするための豊富なツールを提供します。

• 単一項目の作成：詳細なフィールドを持つ1つの項目をリストに追加します。
• 複数項目の一括作成：SlackのAPI制限を考慮したビルトインのレート制限付きで、一度に複数の項目を追加します。
• 項目の取得：オプションのメタデータ付きで項目のリストを取得します。
• 項目のフィルタリング：任意のフィールド値（ステータス、担当者、優先度など）に基づく強力なサーバー側のフィルタリングが可能です。
• データのエクスポート：リスト項目をJSONまたはCSV形式でエクスポートし、分析またはバックアップに使用できます。
• サブタスクの作成：親項目の下にサブ項目を作成します。
• 全フィールドのサポート：すべてのSlack Listフィールドタイプ（テキスト、日付、ユーザー、セレクト、チェックボックスなど）で動作します。
• エラーハンドリング：堅牢なエラーハンドリングと、失敗した操作に対する明確なフィードバックを提供します。
• 本番環境での使用に適しています：ロギング、環境ベースの設定、クリーンなプロジェクト構造が含まれています。

💻 使用例

基本的な使用法

# ここに基本的な使用法のコードを記載する予定ですが、元のREADMEに具体的なコード例がないため省略します。

高度な使用法

# ここに高度な使用法のコードを記載する予定ですが、元のREADMEに具体的なコード例がないため省略します。

📚 ドキュメント

ツールリファレンス

このサーバーは、AIアシスタントに以下のツールを公開しています。各ツールは、直感的かつ強力で、明確な説明とパラメーターが用意されています。

create_list_item

Slack Listに単一の新しい項目を作成します。

説明： このツールは、指定されたSlack Listに1つの項目を作成します。項目には少なくともタイトルフィールドが必要で、必要に応じて追加のフィールドを含めることができます。すべてのフィールド値は、リストのスキーマに対して検証されます。

パラメーター：

• list_id（文字列、必須）：Slack ListのID（例：F1234ABCD）。
• title（文字列、必須）：項目の主なタイトル/テキスト。
• title_column_id（文字列、オプション）：タイトルフィールドの列ID（デフォルトはCol10000000）。
• additional_fields（文字列、オプション）：追加フィールドのJSON文字列。詳細はフィールド形式を参照してください。
• parent_item_id（文字列、オプション）：サブタスクを作成するためのオプションの親項目ID。

使用例：

"私のプロジェクトリストF1234ABCDに、タイトルが'Finish Q4 report'で、期限が2024-12-20の新しいタスクを作成してください。"

create_multiple_list_items

レート制限付きで、Slack Listに複数の項目を作成します。

説明： このツールは、リスト項目の一括作成を可能にします。各項目は、SlackのAPI制限（約1分間に50リクエスト）を尊重するために、適切なレート制限付きで個別に作成されます。

パラメーター：

• list_id（文字列、必須）：Slack ListのID。
• items_data（文字列、必須）：作成する項目のJSON配列。詳細は一括作成形式を参照してください。
• title_column_id（文字列、オプション）：タイトルフィールドの列ID。
• rate_limit_delay（浮動小数点数、オプション）：リクエスト間の遅延時間（秒）（デフォルト：1.2秒）。

使用例：

"私のリストF1234ABCDに、これら3つのタスクを追加してください：1. Design mockups (期限12/10)、2. Write tests (期限12/15)、3. Update documentation (期限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から項目をフィルタリングして取得します。

説明： このツールは、特定のフィールド値でリスト項目を検索およびフィルタリングできます。特定のステータス、担当者、優先度、またはその他のフィールドを持つ項目を見つけるのに便利です。

パラメーター：

• list_id（文字列、必須）：Slack ListのID。
• filter_column_id（文字列、必須）：フィルタリングする列ID。
• filter_value（文字列、必須）：検索する値。
• filter_operator（文字列、オプション）：値の一致方法。オプションについてはフィルター演算子を参照してください。
• max_items（整数、オプション）：処理する最大項目数（デフォルト：100）。

使用例：

"リストF1234ABCDで、私に割り当てられ、'High'優先度にマークされたすべてのタスクを見つけてください。"

export_list_items

Slack Listの項目を構造化データ形式にエクスポートします。

説明： このツールは、オプションのフィルタリング付きで、リスト項目をJSONまたはCSV形式にエクスポートします。バックアップ、分析、または他のシステムとの統合に便利です。

パラメーター：

• list_id（文字列、必須）：Slack Listの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": "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：リストとやり取りするときに、ブラウザの開発者ツールでネットワークリクエストを調べることで列IDを見つけることができます。または、get_list_itemsツールを使用し、出力を調べることもできます。

コントリビューション

コントリビューションは大歓迎です！新機能、バグ修正、または改善のアイデアがある場合は、issueを開くか、プルリクエストを送信してください。詳細についてはCONTRIBUTING.mdを参照してください。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。