Slack MCP Server

Slack ワークスペース内のメッセージを検索する MCP (Model Context Protocol) サーバーです。AI エージェントが Slack のメッセージを効率的に検索・取得できるようにします。

概要

このプロジェクトは、MCP プロトコルに準拠したサーバーを実装し、Slack Web API を使用してワークスペース内のメッセージを検索する機能を提供します。Claude Desktop やその他の MCP クライアントから使用できます。

主な機能

• ✅ MCP プロトコル準拠: 標準的な MCP サーバー実装

• ✅ Slack メッセージ検索: ワークスペース内のメッセージを検索

• ✅ チャンネルフィルタリング: 特定のチャンネルに絞り込んだ検索

• ✅ レート制限対応: Slack API のレート制限を適切に処理

• ✅ エラーハンドリング: 統一されたエラーハンドリング戦略

• ✅ ログ記録: 検索リクエストの統計情報とログ記録

前提条件

• Bun v1.2.21 以降

• 有効な Slack User Token (xoxb- または xoxp- で始まる)

Slack User Token の必要な権限

以下の権限を持つ Slack User Token が必要です：

• channels:history: ユーザーの公開チャンネル内のメッセージとコンテンツを表示

• channels:read: ワークスペース内の公開チャンネルの基本情報を表示

• groups:history: ユーザーのプライベートチャンネル内のメッセージとコンテンツを表示

• groups:read: ユーザーのプライベートチャンネルの基本情報を表示

• im:history: ユーザーのダイレクトメッセージ内のメッセージとコンテンツを表示

• im:read: ユーザーのダイレクトメッセージの基本情報を表示

• mpim:history: ユーザーのグループダイレクトメッセージ内のメッセージとコンテンツを表示

• mpim:read: ユーザーのグループダイレクトメッセージの基本情報を表示

• search:read: ワークスペースのコンテンツを検索

セットアップ

1. リポジトリのクローン

git clone https://github.com/paterapatera/slack-mcp.git
cd slack-mcp

2. 依存関係のインストール

bun install

3. 環境変数の設定

必須の環境変数：

export SLACK_USER_TOKEN="xoxb-your-token-here"

オプションの環境変数：

export SLACK_TEAM_ID="T1234567890"  # チーム/ワークスペース ID
export SLACK_CHANNEL_IDS="C1234567890,C0987654321"  # 検索対象チャンネル（カンマ区切り）

4. ビルド

bun run build

ビルド後、dist/index.js が生成されます。

使用方法

bun link でインストール

ローカル開発環境で使用する場合、bun link を使用します：

# プロジェクトディレクトリで実行
bun link

# グローバルにリンクされた後、どこからでも実行可能
slack-mcp

環境変数を指定する場合：

SLACK_USER_TOKEN="xoxb-your-token" slack-mcp

MCP クライアントとして使用

このサーバーは MCP クライアント（例: Claude Desktop, MCP Inspector）から使用されます。

Claude Desktop での設定

claude_desktop_config.json に以下を追加：

bun link を使用する場合（推奨）：

{
  "mcpServers": {
    "slack-mcp": {
      "command": "slack-mcp",
      "env": {
        "SLACK_USER_TOKEN": "xoxb-your-token-here",
        "SLACK_TEAM_ID": "T1234567890",
        "SLACK_CHANNEL_IDS": "C1234567890,C0987654321"
      }
    }
  }
}

bun link でグローバルにリンクされている場合、slack-mcp コマンドが使用可能になります。

ローカルパスを使用する場合：

{
  "mcpServers": {
    "slack-mcp": {
      "command": "bun",
      "args": ["/path/to/slack-mcp/dist/index.js"],
      "env": {
        "SLACK_USER_TOKEN": "xoxb-your-token-here",
        "SLACK_TEAM_ID": "T1234567890",
        "SLACK_CHANNEL_IDS": "C1234567890,C0987654321"
      }
    }
  }
}

直接実行

bun dist/index.js

ただし、通常は MCP クライアント経由で使用します。

テスト

ユニットテスト

bun test

全80テストが実行され、以下のカバレッジが含まれます：

• Config Service

• Slack API Client

• Search Service

• MCP Server

• Logging Service

• 統合テスト

MCP Inspector を使用した E2E テスト

MCP Inspector を使用してサーバーをテストする方法については、MCP_INSPECTOR_GUIDE.md を参照してください。

簡単な手順：

# 1. 環境変数を設定
export SLACK_USER_TOKEN="xoxb-your-token-here"

# 2. ビルド
bun run build

# 3. MCP Inspector を起動
bun run inspector

または、テストスクリプトを使用：

./scripts/test-with-inspector.sh

詳細は MCP_INSPECTOR_GUIDE.md を参照してください。

アーキテクチャ

主要コンポーネント

• McpServer: MCP プロトコルの実装とツールの登録

• SlackAPIClient: Slack Web API との通信とレート制限処理

• SearchService: メッセージ検索のビジネスロジック

• ConfigService: 環境変数の読み込みと検証

• LoggingService: ログ記録と統計情報の管理

プロジェクト構造

slack-mcp/
├── src/
│   ├── index.ts                 # エントリーポイント
│   └── services/
│       ├── mcp-server.ts        # MCP サーバー実装
│       ├── slack-api-client.ts  # Slack API クライアント
│       ├── search-service.ts     # 検索サービス
│       ├── config-service.ts    # 設定管理
│       ├── logging-service.ts   # ログ記録
│       └── __tests__/           # テストファイル
├── dist/                        # ビルド出力
├── scripts/                     # ユーティリティスクリプト
└── .kiro/                      # 仕様書と設計ドキュメント

ツール

search_messages

Slack ワークスペース内のメッセージを検索します。

パラメータ:

• query (string, 必須): 検索クエリ

• limit (number, オプション): 検索結果の最大件数

戻り値:

{
  "messages": [
    {
      "text": "メッセージのテキスト",
      "timestamp": "2024-01-01T00:00:00.000Z",
      "channelId": "C1234567890",
      "channelName": "general",
      "userId": "U1234567890",
      "userName": "username"
    }
  ],
  "total": 1,
  "hasMore": false
}

環境変数

トラブルシューティング

サーバーが起動しない

• 環境変数 SLACK_USER_TOKEN が正しく設定されているか確認

• トークンが有効な形式（xoxb- または xoxp- で始まる）か確認

• dist/index.js が存在するか確認（bun run build を実行）

検索が失敗する

• Slack API の認証トークンが有効か確認

• トークンに必要なスコープ（search:read）が付与されているか確認

• ネットワーク接続を確認

MCP Inspector でエラーが発生する

• ログが stdout に出力されていないか確認（すべて stderr に出力される必要があります）

• 詳細は MCP_INSPECTOR_GUIDE.md のトラブルシューティングセクションを参照

開発

開発環境のセットアップ

# 依存関係のインストール
bun install

# 開発モードでテストを実行
bun test --watch

# ビルド
bun run build

コードスタイル

• TypeScript を使用

• TDD (Test-Driven Development) アプローチ

• 統一エラーハンドリング戦略に準拠

ライセンス

ISC

参考リンク

• MCP Inspector ガイド

• Model Context Protocol

• Slack API ドキュメント

• Bun ドキュメント

貢献

このプロジェクトは個人プロジェクトです。問題や改善提案がある場合は、Issue を作成してください。

注意: このプロジェクトは bun link を使用したローカル開発環境での利用を想定しています。npm への公開は想定していません。