slack-lists-mcp

Slack Lists MCP サーバー

AI アシスタントに Slack Lists の完全な読み取り・書き込みアクセスを提供する Model Context Protocol（MCP）サーバーです。

このサーバーは AI モデルと Slack をつなぐブリッジとして機能し、標準化されたプロトコルを通じて、Slack List のアイテムの作成、取得、更新、削除、フィルタリング、管理をシームレスに実行できるようにします。Claude Desktop などの AI アシスタントが、Slack 内のタスク、プロジェクト、データを管理する強力な生産性ツールとして活用できるようになります。

このプロジェクトは、次の機能を備えた完全なパッケージを提供します：

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

書き込み操作は、実際の Slack ワークスペースで検証済みです（検証状況を参照してください）。

機能

この MCP サーバーは、Slack Lists を操作するための豊富なツールを提供します：

• 単一アイテムの作成：詳細なフィールドを指定して、リストにアイテムを1つ追加します。
• アイテムの一括作成：Slack API のレート制限を順守する組み込みのレート制限機能を使って、複数のアイテムを一度に追加します。
• アイテムの取得：任意のメタデータとともに、アイテムのリストを取得します。
• アイテムの更新：既存アイテムの任意のセルを更新できます。タスクの完了、担当者の変更、スケジュールの変更、任意のフィールドの編集など、タスクをすべて管理できます。
• アイテムの削除：リストからアイテムを完全に削除します。
• 列の検出：既存のアイテムからリストの列 ID、型、選択肢 ID を推定します（Slack にはスキーマ API がないため、ブラウザーの開発者ツールで ID を探す手間を省けます）。
• アイテムのフィルタリング：ステータス、担当者、優先度など、任意のフィールド値に基づいてサーバー側で強力なフィルタリングを行います。
• データのエクスポート：分析やバックアップのために、リストアイテムを JSON または CSV 形式でエクスポートします。
• サブタスクの作成：親アイテムの下にサブアイテムを作成します。
• すべてのフィールド型に対応：Slack List のすべてのフィールド型（テキスト、日付、ユーザー、選択肢、チェックボックス、数値、メールアドレス、電話番号）を利用できます。
• エラー処理：堅牢なエラー処理により、操作が失敗した場合に明確なフィードバックを提供します。

はじめに

以下の手順に沿って、Slack Lists MCP サーバーを起動してください。

前提条件

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

1. Slack アプリを作成する

1. Slack API website にアクセスし、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 にアイテムを 1 つ作成します。アイテムには少なくともタイトルフィールドが必要で、必要に応じて追加のフィールドを含めることができます。すべてのフィールド値は、リストのスキーマに照らして検証されます。

パラメーター：

• list_id（string、必須）：Slack List の ID（例：F1234ABCD）。
• title（string、必須）：アイテムのメインタイトル／テキスト。
• title_column_id（string、省略可能）：タイトルフィールドの列 ID（デフォルトは Col10000000）。
• additional_fields（string、省略可能）：追加フィールドを含む JSON 文字列。詳細はフィールド形式を参照してください。
• parent_item_id（string、省略可能）：サブタスクを作成する場合に指定する親アイテム ID。

プロンプトの例：

「プロジェクトリスト F1234ABCD に、タイトルを『Finish Q4 report』、期限を 2024-12-20 として新しいタスクを作成してください。」

---

create_multiple_list_items

レート制限を適用しながら、Slack List に複数のアイテムを作成します。

説明： このツールでは、リストアイテムを一括作成できます。Slack の API 制限（1 分あたり約 50 リクエスト）を守るため、適切なレート制限を適用しながら各アイテムを個別に作成します。

パラメーター：

• list_id（string、必須）：Slack List の ID。
• items_data（string、必須）：作成するアイテムの JSON 配列。詳細は一括作成形式を参照してください。
• title_column_id（string、省略可能）：タイトルフィールドの列 ID。
• rate_limit_delay（float、省略可能）：リクエスト間の遅延（秒、デフォルト：1.2s）。

プロンプトの例：

「次の 3 つのタスクをリスト F1234ABCD に追加してください：1. モックアップをデザインする（期限 12/10）、2. テストを作成する（期限 12/15）、3. ドキュメントを更新する（期限 12/20）。」

---

get_list_items

Slack List からアイテムを取得します。

説明： このツールは、オプションのメタデータとともに、指定した Slack List からアイテムを取得します。リストの現在の内容を確認したり、アイテムの詳細を調べたり、フィルタリング用のデータを準備したりするために使用します。

パラメーター：

• list_id（string、必須）：Slack List の ID。
• limit（integer、省略可能）：取得するアイテムの最大数（デフォルト：50、最大：100）。
• include_metadata（boolean、省略可能）：作成／更新のメタデータを含めるかどうか（デフォルト：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 リストアイテム（行）の 1 つ以上のセルを更新します。タスクのチェック、担当者の変更、スケジュールの変更、任意のフィールドの編集など、タスク管理全般を 1 回の呼び出しで行うツールです。

説明： row_id で特定したアイテムの指定列を更新します。get_list_items または filter_list_items を使って row_id を取得してください。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 を調べる際に使用してください。

**注：**列の値が少なくとも 1 つのアイテムに設定されている場合にのみ、その列を特定できます。空の列は表示されません。

パラメーター：

• 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 と列 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 はすべて正しく往復処理できます。

公開ドキュメントと異なるフィールド形式が 1 つあります。チェックボックスのセルには、そのままのブール値を指定します（"checkbox": true）。ドキュメントでは "checkbox": [boolean] とされていますが、実際の API は配列形式を invalid_arguments で拒否し、値をそのままのブール値で返すため、このサーバーではそのままのブール値を送信します。

クレジット

このプロジェクトは maplehilllabs/mcp-slack-lists（MIT）をベースとし、update_list_item、delete_list_item、discover_list_columns と、すべてのフィールドタイプへの完全な対応を追加したものです。

ライセンス

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