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 | ✅ | Slack User Token (xoxb- または xoxp- で始まる) |
SLACK_TEAM_ID | ❌ | チーム/ワークスペース ID |
SLACK_CHANNEL_IDS | ❌ | 検索対象チャンネル ID（カンマ区切り） |
トラブルシューティング
サーバーが起動しない
- 環境変数
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
参考リンク
貢献
このプロジェクトは個人プロジェクトです。問題や改善提案がある場合は、Issue を作成してください。
注意: このプロジェクトは bun link を使用したローカル開発環境での利用を想定しています。npm への公開は想定していません。