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 API の 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 への公開は想定していません。

slack-mcp