BullMQ MCP

BullMQ MCP サーバー - BullMQ キュー管理のための Model Context Protocol

BullMQ の Redis ベースのジョブキューを管理するための、包括的な BullMQ MCP（Model Context Protocol）サーバーです。この BullMQ MCP 統合により、Claude Desktop などの AI アシスタントが自然言語を通じて BullMQ キューを操作し、ジョブのステータスを監視し、ワーカーを管理して、キュー操作を実行できます。

キーワード: BullMQ MCP、BullMQ Model Context Protocol、BullMQ Claude 統合、BullMQ AI アシスタント、BullMQ キュー管理、Redis キュー MCP

機能

• 🔌 接続管理: 複数の Redis インスタンスに接続し、インスタンスを切り替えられます
• 📊 キュー操作: キューの一覧表示、一時停止、再開、空にする操作、クリーンアップを行えます
• ⚙️ ジョブ管理: ジョブの追加、削除、再試行、昇格を行えます
• 📈 ジョブ監視: ジョブの詳細、ログ、統計情報を確認できます
• 🧹 一括操作: 設定可能な上限数で、ステータスごとにジョブをクリーンアップできます
• 🔄 複数接続: 異なる Redis インスタンス（開発、ステージング、本番）を管理できます
• 📝 ジョブログ: ジョブにカスタムログエントリーを追加して確認できます
• 🎯 柔軟なステータスフィルタリング: さまざまな状態（active、waiting、completed、failed、delayed）でジョブを検索できます

インストール - BullMQ MCP のセットアップ

Smithery 経由でのインストール

Smithery を使って、Claude Desktop 用の BullMQ Queue Management Server を自動でインストールするには、次のコマンドを実行します。

npx -y @smithery/cli install @adamhancock/bullmq-mcp --client claude

NPM によるインストール

npm install -g @adamhancock/bullmq-mcp

または、pnpm を使用します。

pnpm install -g @adamhancock/bullmq-mcp

または、yarn を使用します。

yarn global add @adamhancock/bullmq-mcp

Docker によるインストール

GitHub Container Registry から Docker イメージを取得します。

docker pull ghcr.io/adamhancock/bullmq-mcp:latest

または、特定のバージョンを使用します。

docker pull ghcr.io/adamhancock/bullmq-mcp:v1.0.0

使用方法 - Claude Desktop で BullMQ MCP を設定する

Claude Desktop の設定

クイックセットアップ（推奨）

Claude CLI がインストールされている場合は、次のコマンドを 1 つ実行するだけで BullMQ サーバーを追加できます。

npm パッケージを使用する場合:

claude mcp add --scope user bullmq -- npx -y @adamhancock/bullmq-mcp

Docker を使用する場合:

claude mcp add-json bullmq --scope user '{"command": "docker", "args": ["run", "-i", "--rm", "-e", "REDIS_URL=redis://host.docker.internal:6379", "ghcr.io/adamhancock/bullmq-mcp:latest"], "scope": "user"}'

Redis URL 環境変数を使用する場合:

# NPM version
claude mcp add --scope user bullmq -e REDIS_URL=redis://localhost:6379 -- npx -y @adamhancock/bullmq-mcp

# Docker version with environment variable
claude mcp add-json bullmq --scope user '{"command": "docker", "args": ["run", "-i", "--rm", "-e", "REDIS_URL=redis://host.docker.internal:6379", "ghcr.io/adamhancock/bullmq-mcp:latest"], "scope": "user"}'

注: claude mcp add で Docker を使用する場合、ホストマシンで実行中の Redis に接続するには、localhost の代わりに host.docker.internal を使用してください。

手動設定

Claude Desktop を手動で設定するには、次の内容を Claude の設定ファイルに追加します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bullmq": {
      "command": "npx",
      "args": ["-y", "@adamhancock/bullmq-mcp"]
    }
  }
}

Redis URL を使用する場合:

{
  "mcpServers": {
    "bullmq": {
      "command": "npx",
      "args": ["-y", "@adamhancock/bullmq-mcp"],
      "env": {
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

その他の設定方法:

グローバルインストールを使用する場合:

{
  "mcpServers": {
    "bullmq": {
      "command": "bullmq-mcp"
    }
  }
}

ローカルインストールを使用する場合:

{
  "mcpServers": {
    "bullmq": {
      "command": "node",
      "args": ["/path/to/bullmq-mcp/dist/index.js"]
    }
  }
}

Docker を使用する場合:

{
  "mcpServers": {
    "bullmq": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/adamhancock/bullmq-mcp:latest"],
      "env": {
        "REDIS_URL": "redis://host.docker.internal:6379"
      }
    }
  }
}

注: Docker を使用する場合、ホストマシンで実行中の Redis に接続するには、localhost の代わりに host.docker.internal を使用してください。

利用可能な BullMQ MCP ツール

接続管理

• connect - Redis インスタンスに接続します

  {
    id: string,          // Connection identifier
    url?: string,        // Redis URL (e.g., redis://user:pass@localhost:6379/0)
    host?: string,       // Redis host (default: localhost) - ignored if url is provided
    port?: number,       // Redis port (default: 6379) - ignored if url is provided
    password?: string,   // Redis password (optional) - ignored if url is provided
    db?: number         // Redis database number (default: 0) - ignored if url is provided
  }
  

  ツールは次の優先順位で Redis URL を使用します。

  1. 指定されている場合は url パラメーター
  2. 設定されている場合は REDIS_URL 環境変数
  3. 個別の接続パラメーター（host、port、password、db）

  Docker の自動リダイレクト: Docker コンテナー内で実行している場合（DOCKER 環境変数または DOCKER_HOST によって検出）、 ホストマシン上の Redis に接続できるよう、localhost は自動的に host.docker.internal にリダイレクトされます。

• disconnect - 現在の Redis インスタンスから切断します

• list_connections - 保存済みの接続をすべて一覧表示します

• switch_connection - 別の接続に切り替えます

  {
    id: string  // Connection identifier to switch to
  }
  

キュー管理

• list_queues - 現在の接続にあるキューをすべて一覧表示します

  {
    pattern?: string  // Queue name pattern (supports wildcards, default: "*")
  }
  

• stats - キューの統計情報を取得します

  {
    queue: string  // Queue name
  }
  

• pause_queue - キューの処理を一時停止します

  {
    queue: string  // Queue name
  }
  

• resume_queue - キューの処理を再開します

  {
    queue: string  // Queue name
  }
  

• drain_queue - キューからすべてのジョブを削除します

  {
    queue: string  // Queue name
  }
  

• clean_queue - キューからジョブをクリーンアップします

  {
    queue: string,        // Queue name
    grace?: number,       // Grace period in milliseconds (default: 0)
    limit?: number,       // Maximum number of jobs to clean (default: 1000)
    status?: "completed" | "failed"  // Job status to clean (default: "completed")
  }
  

ジョブ管理

• get_jobs - ステータスでキュー内のジョブを取得

  {
    queue: string,     // Queue name
    status: "active" | "waiting" | "completed" | "failed" | "delayed" | "paused" | "repeat" | "wait",
    start?: number,    // Start index (default: 0)
    end?: number      // End index (default: 10)
  }
  

• get_job - ID で特定のジョブを取得

  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  

• add_job - 新しいジョブをキューに追加

  {
    queue: string,      // Queue name
    name: string,       // Job name
    data: object,       // Job data (JSON object)
    opts?: {            // Job options
      delay?: number,           // Delay in milliseconds
      priority?: number,        // Job priority
      attempts?: number,        // Number of attempts
      backoff?: object,         // Backoff configuration
      removeOnComplete?: boolean,  // Remove job when completed
      removeOnFail?: boolean    // Remove job when failed
    }
  }
  

• remove_job - キューからジョブを削除

  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  

• retry_job - 失敗したジョブを再試行

  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  

• promote_job - 遅延ジョブを昇格

  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  

ジョブログ

• get_job_logs - ジョブのログを取得

  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  

• add_job_log - ジョブにログエントリを追加

  {
    queue: string,   // Queue name
    jobId: string,   // Job ID
    message: string  // Log message
  }
  

BullMQ MCP の例 - Claude で BullMQ を使用する方法

Redis に接続してキューを一覧表示する

// Connect using Redis URL
await use_mcp_tool("bullmq", "connect", {
  id: "local",
  url: "redis://localhost:6379"
});

// Or connect using individual parameters
await use_mcp_tool("bullmq", "connect", {
  id: "local",
  host: "localhost",
  port: 6379,
  password: "mypassword",
  db: 0
});

// Or connect using REDIS_URL environment variable
// (no url parameter needed if REDIS_URL is set)
await use_mcp_tool("bullmq", "connect", {
  id: "local"
});

// List all queues
await use_mcp_tool("bullmq", "list_queues", {});

ジョブを追加して監視する

// Add a job with delay
await use_mcp_tool("bullmq", "add_job", {
  queue: "email-queue",
  name: "send-welcome-email",
  data: {
    to: "[email protected]",
    subject: "Welcome!",
    template: "welcome"
  },
  opts: {
    delay: 5000,        // Process after 5 seconds
    priority: 1,        // Higher priority (lower number = higher priority)
    attempts: 3,        // Retry up to 3 times
    backoff: {
      type: "exponential",
      delay: 2000
    }
  }
});

// Get job status
await use_mcp_tool("bullmq", "get_job", {
  queue: "email-queue",
  jobId: "1"
});

// Add a custom log entry
await use_mcp_tool("bullmq", "add_job_log", {
  queue: "email-queue",
  jobId: "1",
  message: "Email template rendered successfully"
});

// View job logs
await use_mcp_tool("bullmq", "get_job_logs", {
  queue: "email-queue",
  jobId: "1"
});

キューのメンテナンス

// Get queue statistics
await use_mcp_tool("bullmq", "stats", {
  queue: "email-queue"
});
// Returns: active, waiting, completed, failed, delayed, paused counts

// Get failed jobs with details
await use_mcp_tool("bullmq", "get_jobs", {
  queue: "email-queue",
  status: "failed",
  start: 0,
  end: 20
});

// Retry a specific failed job
await use_mcp_tool("bullmq", "retry_job", {
  queue: "email-queue",
  jobId: "123"
});

// Clean completed jobs older than 1 hour
await use_mcp_tool("bullmq", "clean_queue", {
  queue: "email-queue",
  grace: 3600000,  // 1 hour in milliseconds
  status: "completed",
  limit: 100       // Clean max 100 jobs
});

// Pause processing
await use_mcp_tool("bullmq", "pause_queue", {
  queue: "email-queue"
});

// Resume processing
await use_mcp_tool("bullmq", "resume_queue", {
  queue: "email-queue"
});

// Completely drain a queue (remove ALL jobs)
await use_mcp_tool("bullmq", "drain_queue", {
  queue: "test-queue"
});

高度なジョブ管理

// Add a repeating job
await use_mcp_tool("bullmq", "add_job", {
  queue: "metrics-queue",
  name: "collect-metrics",
  data: { source: "api" },
  opts: {
    repeat: {
      pattern: "*/5 * * * *"  // Every 5 minutes (cron syntax)
    }
  }
});

// Promote a delayed job to be processed immediately
await use_mcp_tool("bullmq", "promote_job", {
  queue: "notification-queue",
  jobId: "456"
});

// Get jobs by different statuses
const statuses = ["active", "waiting", "completed", "failed", "delayed"];
for (const status of statuses) {
  await use_mcp_tool("bullmq", "get_jobs", {
    queue: "worker-queue",
    status: status,
    start: 0,
    end: 5
  });
}

BullMQ MCP を始める

前提条件

1. Redis サーバー：Redis がローカルで実行されているか、リモートからアクセスできることを確認します

   # Check if Redis is running
   redis-cli ping
   # Should return: PONG
   

2. Claude Desktop：BullMQ MCP サーバーをインストールして設定した Claude Desktop を用意します

基本的なワークフロー

1. Redis に接続する

   Connect to Redis using the bullmq tool with id "local"
   

2. キューを確認する

   List all queues and show me their statistics
   

3. ジョブを監視する

   Show me failed jobs in the email-queue
   

4. ジョブを管理する

   Add a test job to my-queue with some sample data
   

Docker の使用上の注意

Docker 版を使用する場合：

• Redis 接続：Docker で実行中の場合、サーバーは localhost を host.docker.internal に自動的にリダイレクトするため、次のどちらも使用できます。
  • redis://localhost:6379（自動的にリダイレクトされます）
  • redis://host.docker.internal:6379（Docker ホストを明示的に指定）
• 接続タイムアウト：到達できないホストへの接続が停止しないよう、接続のタイムアウトは 10 秒に設定されています
• 環境変数：REDIS_URL=redis://localhost:6379 を設定します。Docker では自動的にリダイレクトされます
• ネットワークアクセス：Docker コンテナが Redis インスタンスに接続できるよう、ネットワークアクセスが必要です
• 永続性：コンテナは一時的なもので、すべてのデータはコンテナではなく Redis に保存されます

BullMQ MCP の一般的なユースケース

1. キューの健全性を監視する

Check the health of all my queues - show me which ones have failed or stuck jobs

2. 失敗したジョブをデバッグする

Show me the failed jobs in the payment-queue and their error messages

3. 失敗したジョブを再試行する

Retry all failed jobs in the notification-queue

4. キューのメンテナンス

Clean up completed jobs older than 24 hours from all queues

5. 複数の環境を管理する

// Connect to different Redis instances
await use_mcp_tool("bullmq", "connect", {
  id: "production",
  url: "redis://prod-redis.example.com:6379"
});

await use_mcp_tool("bullmq", "connect", {
  id: "staging",
  url: "redis://staging-redis.example.com:6379"
});

// Switch between connections
await use_mcp_tool("bullmq", "switch_connection", {
  id: "production"
});

接続をテストする

Claude Desktop を設定した後、Claude を再起動して接続をテストします。

1. Claude Desktop を開きます
2. 新しい会話を開始します
3. MCP 接続をテストします。

Can you connect to my local Redis using the bullmq tool? Use connection id "local" with default settings.

成功すると、確認メッセージが表示されます。その後、次の操作を行えます。

• 利用可能なすべてのキューを一覧表示する
• キューの統計情報を確認する
• ジョブの詳細を表示する
• キューを操作する

開発

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run built version
pnpm start

# Create global link
pnpm link --global

トラブルシューティング

接続の問題

• Redis が実行されていない：指定したホストとポートで Redis が実行されていることを確認します

  # Start Redis (macOS with Homebrew)
  brew services start redis
  
  # Start Redis (Linux)
  sudo systemctl start redis
  
  # Test connection
  redis-cli ping
  

• 認証に失敗した：Redis のパスワード（設定されている場合）が正しいことを確認します

  # Test with password
  redis-cli -a yourpassword ping
  

• データベースが間違っている：正しい Redis データベース番号に接続していることを確認します

よくあるエラー

• 「アクティブな接続がありません」：ほかの操作を行う前に、まず connect ツールを使用します

  First connect to Redis with: connect to Redis using bullmq with id "local"
  

• 「ジョブが見つかりません」：指定したキューにジョブ ID が存在することを確認します

  List jobs in the queue first to see available job IDs
  

• 「キューが見つかりません」：キューが存在しないか、まだジョブがない可能性があります

  List all queues to see what's available
  

• 接続タイムアウト：ファイアウォールの設定と Redis のバインドアドレスを確認します

  # Check Redis config
  grep "^bind" /etc/redis/redis.conf
  

MCP サーバーの問題

• サーバーが起動しない：Claude Desktop の設定ファイルの構文を確認します
• ツールを利用できない：設定を変更した後、Claude Desktop を再起動します
• アクセスが拒否された：MCP サーバーに実行権限があることを確認します

デバッグ

1. Claude Desktop で詳細ログを有効にする：

   • ターミナルから Claude を実行してログを確認します
   • macOS：/Applications/Claude.app/Contents/MacOS/Claude
   • Windows：コマンドプロンプトから Claude を実行します
   • Linux：ターミナルから実行します

2. MCP サーバーを直接テストする：

   # Run the server manually to check for errors
   npx @adamhancock/bullmq-mcp
   

3. Redis 接続を確認する：

   # Test Redis connectivity
   redis-cli -h localhost -p 6379 ping
   
   # Check Redis info
   redis-cli info clients
   

4. 環境変数を確認する：

   # Check if REDIS_URL is set
   echo $REDIS_URL
   

要件

• Node.js 18+
• Redis サーバー
• BullMQ 互換の Redis 設定

BullMQ MCP を使用する理由

BullMQ MCP サーバーは、AI アシスタントと BullMQ のジョブキュー管理との間のギャップを埋めます。この MCP 統合により、次のことができます。

• 自然言語によるキュー管理：会話形式のコマンドを使って BullMQ キューを管理できます
• AI を活用したデバッグ：Claude に失敗したジョブを分析させ、解決策を提案させることができます
• キュー監視の自動化：AI を通じてインテリジェントなアラートと監視を設定できます
• 環境をまたいだ管理：開発、ステージング、本番環境のキューをシームレスに切り替えられます

BullMQ MCP と従来のツールの比較

機能	BullMQ MCP	従来の CLI／GUI
自然言語コマンド	✅ はい	❌ いいえ
AI 支援によるデバッグ	✅ はい	❌ いいえ
一括操作	✅ はい	⚠️ 制限あり
学習の難易度	✅ 最小限	⚠️ 中程度
AI ツールとの統合	✅ ネイティブ	❌ なし

関連プロジェクト

• BullMQ - 強力な Node.js ジョブキュー
• Model Context Protocol - AI ツールとの統合を可能にするプロトコル
• Claude Desktop - MCP をサポートする AI アシスタント

貢献

BullMQ MCP サーバーへの貢献を歓迎します。この統合を改善するための Issue やプルリクエストをぜひお寄せください。

サポート

次の項目に関する問題については：

• BullMQ MCP サーバー：GitHub の Issue
• BullMQ：BullMQ ドキュメント
• MCP プロトコル：MCP ドキュメント

ライセンス

MIT

---

検索キーワード：BullMQ MCP、BullMQ Model Context Protocol、BullMQ Claude、BullMQ AI 統合、BullMQ キュー管理 MCP、Redis キュー MCP、BullMQ 自動化、BullMQ 自然言語、BullMQ Claude Desktop、BullMQ 用 MCP サーバー