home / mcp / bullmq mcp server

BullMQ MCP Server

Provides a BullMQ MCP server to connect to Redis, manage queues, and operate jobs via MCP clients.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can manage BullMQ Redis-based queues through a dedicated MCP server that lets you connect to Redis instances, inspect queues and jobs, and perform queue and job operations using conversational or scripted commands. This server enables multiple connections, real-time monitoring, and bulk maintenance, all from your preferred MCP client or Claude Desktop.

How to use

Connect to a Redis instance to begin managing BullMQ queues. Once connected, you can list queues, view statistics, pause or resume processing, drain or clean queues, and manage individual jobs by adding, retrying, promoting, or removing them. You can also inspect job logs and add custom log entries. Use status-based queries to filter jobs by active, waiting, completed, failed, or delayed states, and switch between multiple Redis connections as needed for development, staging, and production.

How to install

# Prerequisites: ensure you have Node.js 18+, Redis server running, and an MCP client ready

# Global NPM installation
npm install -g @adamhancock/bullmq-mcp

# OR using NPX to run directly without installing
npx -y @adamhancock/bullmq-mcp

# Docker installation (pulls the latest image)
docker pull ghcr.io/adamhancock/bullmq-mcp:latest

Additional configurations and notes

The server supports multiple ways to run and configure the MCP for BullMQ. You can install globally and run the tool directly, or run it via Docker with Redis connection details supplied through environment variables. If you run the Docker container, Redis connections can be redirected from localhost to the host machine when running on Docker.

# Manual JSON-based Claude Desktop configuration example (local setup)
{
  "mcpServers": {
    "bullmq": {
      "command": "npx",
      "args": ["-y", "@adamhancock/bullmq-mcp"]
    }
  }
}
```

```
# Manual JSON-based Claude Desktop configuration with REDIS_URL
{
  "mcpServers": {
    "bullmq": {
      "command": "npx",
      "args": ["-y", "@adamhancock/bullmq-mcp"],
      "env": {
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}
```

```
# Docker-based runtime example
{
  "mcpServers": {
    "bullmq": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "REDIS_URL=redis://host.docker.internal:6379", "ghcr.io/adamhancock/bullmq-mcp:latest"]
      
    }
  }
}
```

Note: When using Docker, use host.docker.internal for Redis connections to reach the host machine's Redis from inside the container.

Troubleshooting and tips

If you encounter connection timeouts or missing queues, verify your Redis URL and database configuration, ensure Redis is reachable from the MCP instance, and confirm the MCP tool is correctly connected before issuing other commands.

Tools and capabilities

The BullMQ MCP server exposes a range of tools to manage connections, queues, jobs, and logs. You can connect or disconnect from Redis, list connections, switch between them, list queues, retrieve statistics, pause or resume queues, drain or clean queues, and perform job operations such as getting, adding, removing, retrying, and promoting jobs. You can also fetch and add job logs.

Getting started with tests and examples

After configuring and starting the MCP server, you can interact with it through an MCP client or Claude Desktop using commands like connecting to a Redis instance, listing queues, inspecting jobs, and performing maintenance actions. Start with a simple connect operation, then explore queues and job details before performing more advanced actions.

Notes on production and environments

You can manage multiple Redis instances for development, staging, and production. Switch connections as needed to work with different environments, and ensure proper permissions and network access for each Redis host.

Available tools

connect

Connect to a Redis instance by URL or parameters to start managing BullMQ queues.

disconnect

Disconnect from the current Redis connection.

list_connections

List all saved Redis connections.

switch_connection

Switch to a different Redis connection by its identifier.

list_queues

List all queues in the current connection, with optional pattern filtering.

stats

Get queue statistics such as counts of active, waiting, completed, failed, and delayed jobs.

pause_queue

Pause processing for a specified queue.

resume_queue

Resume processing for a specified queue.

drain_queue

Remove all jobs from a specified queue.

clean_queue

Clean jobs by status with optional grace and limit.

get_jobs

Retrieve jobs from a queue by status with optional start/end indices.

get_job

Get a specific job by ID from a queue.

add_job

Add a new job to a queue with data and options.

remove_job

Remove a specific job from a queue.

retry_job

Retry a failed job in a queue.

promote_job

Promote a delayed job to be processed sooner.

get_job_logs

Fetch logs for a specific job.

add_job_log

Add a log entry to a specific job.