BullMQ MCP Server

BullMQ MCP Server - Model Context Protocol for BullMQ Queue Management

A comprehensive BullMQ MCP (Model Context Protocol) server for managing BullMQ Redis-based job queues. This BullMQ MCP integration enables Claude Desktop and other AI assistants to interact with BullMQ queues, monitor job status, manage workers, and perform queue operations through natural language.

Keywords: BullMQ MCP, BullMQ Model Context Protocol, BullMQ Claude integration, BullMQ AI assistant, BullMQ queue management, Redis queue MCP

Features

• 🔌 Connection Management: Connect to multiple Redis instances and switch between them
• 📊 Queue Operations: List, pause, resume, drain, and clean queues
• ⚙️ Job Management: Add, remove, retry, and promote jobs
• 📈 Job Monitoring: View job details, logs, and statistics
• 🧹 Bulk Operations: Clean jobs by status with configurable limits
• 🔄 Multiple Connections: Manage different Redis instances (development, staging, production)
• 📝 Job Logs: Add and view custom log entries for jobs
• 🎯 Flexible Status Filtering: Query jobs by various states (active, waiting, completed, failed, delayed)

Installation - BullMQ MCP Setup

Installing via Smithery

To install BullMQ Queue Management Server for Claude Desktop automatically via Smithery:

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

NPM Installation

npm install -g @adamhancock/bullmq-mcp

Or with pnpm:

pnpm install -g @adamhancock/bullmq-mcp

Or with yarn:

yarn global add @adamhancock/bullmq-mcp

Docker Installation

Pull the Docker image from GitHub Container Registry:

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

Or use a specific version:

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

Usage - Configure BullMQ MCP with Claude Desktop

Claude Desktop Configuration

Quick Setup (Recommended)

If you have the Claude CLI installed, you can add the BullMQ server with a single command:

Using npm package:

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

Using 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"}'

With Redis URL environment variable:

# 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"}'

Note: When using Docker with claude mcp add, use host.docker.internal instead of localhost to connect to Redis running on your host machine.

Manual Configuration

To manually configure Claude Desktop, add the following to your Claude configuration file:

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"]
    }
  }
}

With Redis URL:

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

Alternative configurations:

Using global installation:

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

Using local installation:

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

Using Docker:

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

Note: When using Docker, use host.docker.internal instead of localhost to connect to Redis running on your host machine.

Available BullMQ MCP Tools

Connection Management

• connect - Connect to a Redis instance

  {
    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 (opt