# BullMQ MCP Server - Model Context Protocol for BullMQ Queue Management

> **Fork notice.** This package is a fork of [`@adamhancock/bullmq-mcp`](https://github.com/adamhancock/bullmq-mcp) by Adam Hancock. All credit for the original implementation goes to the upstream project. This fork adds:
>
> - **Redis Cluster support** (e.g. AWS ElastiCache cluster mode) with automatic slot discovery; `list_queues` and DLQ scans iterate every master node via SCAN.
> - **Configurable BullMQ key prefix** per connection, including a `$QUEUE` placeholder (e.g. `bullmq:{$QUEUE}`) for cluster hash-tagged deployments.
> - **SCAN-based queue discovery** in place of `KEYS`, safe to run against large production Redis instances.
>
> If you don't need the above, prefer the upstream package.

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.

## Features

- **🔌 Connection Management**: Connect to multiple Redis instances and switch between them
- **🧩 Redis Cluster Support**: Connect to Redis Cluster (e.g. AWS ElastiCache cluster mode) with automatic slot discovery; `list_queues` and DLQ scans iterate every master node via SCAN
- **🏷️ Configurable Prefix**: Override BullMQ's default `bull` key prefix per connection. Supports a `$QUEUE` placeholder (e.g. `bullmq:{$QUEUE}`) for cluster hash-tagged deployments
- **📊 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

```bash
npm install -g @mmollick/bullmq-mcp
```

Or with pnpm:

```bash
pnpm install -g @mmollick/bullmq-mcp
```

Or with yarn:

```bash
yarn global add @mmollick/bullmq-mcp
```

## Environment variables

Every field on the `connect` tool falls back to an environment variable when not provided in the args. This lets you bake credentials and topology into your MCP launch config (e.g. via `-e` flags) and call `connect` with just an `id`.

| Variable | Purpose |
| --- | --- |
| `REDIS_URL` | Full Redis URL (`redis://` or `rediss://`). Takes precedence over host/port. |
| `REDIS_HOST` | Redis host when no URL is set. Defaults to `localhost`. |
| `REDIS_PORT` | Redis port when no URL is set. Defaults to `6379`. |
| `REDIS_PASSWORD` | Password. Applied when no URL credentials are present, or as an explicit override. |
| `REDIS_USERNAME` | Username (Redis 6+ ACLs). |
| `REDIS_DB` | Database index (non-cluster only). Defaults to `0`. |
| `REDIS_TLS` | Truthy (`1`/`true`/`yes`/`on`) forces TLS even on `redis://` URLs or host+port. Auto-enabled for `rediss://`. |
| `REDIS_CLUSTER` | Truthy enables Redis Cluster mode. |
| `REDIS_CLUSTER_NODES` | Comma-separated `host:port` seed nodes; implies cluster mode. |
| `REDIS_SLOTS_REFRESH_TIMEOUT` | Cluster mode only. Milliseconds ioredis waits for the `CLUSTER SLOTS` refresh before failing. Raise this (e.g. `10000`) for high-latency tunnels/VPNs. Defaults to ioredis's `1000`. |
| `REDIS_SLOTS_REFRESH_INTERVAL` | Cluster mode only. Milliseconds between periodic `CLUSTER SLOTS` refreshes. Defaults to ioredis's `5000`. |
| `BULLMQ_PREFIX` | BullMQ key prefix template. Supports `$QUEUE` placeholder for cluster hash-tagging (e.g. `bullmq:{$QUEUE}`). Defaults to `bull`. |

Args passed to `connect` always win over env vars; env vars fill in the gaps.

## Usage - Configure BullMQ MCP with Claude Desktop

### Quick Setup (Claude CLI)

```bash
claude mcp add --scope user bullmq -- npx -y @mmollick/bullmq-mcp
```

With a Redis URL:

```bash
claude mcp add --scope user bullmq -e REDIS_URL=redis://localhost:6379 -- npx -y @mmollick/bullmq-mcp
```

### Manual Configuration

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`

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

With Redis URL:

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

Using a global installation:

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

Using a local installation:

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

### Available BullMQ MCP Tools

#### Connection Management

- **connect** - Connect to a Redis instance
  ```typescript
  {
    id: string,          // Connection identifier (required)
    url?: string,        // Redis URL (e.g., redis://user:pass@host:6379/0 or rediss://...)
    host?: string,       // Redis host (used only when no url is resolved)
    port?: number,       // Redis port (used only when no url is resolved)
    password?: string,   // Redis password
    username?: string,   // Redis username (Redis 6+ ACLs)
    db?: number,         // Redis database number (non-cluster only)
    tls?: boolean,       // Force TLS (auto-enabled for rediss:// URLs)
    cluster?: boolean,   // Connect in Redis Cluster mode
    nodes?: string[],    // Cluster seed nodes as 'host:port'; implies cluster=true
    prefix?: string      // BullMQ key prefix template ($QUEUE placeholder supported)
  }
  ```

  Every field falls back to its environment-variable equivalent (see [Environment variables](#environment-variables)) when not supplied. Args always win over env; env fills in the gaps.

- **disconnect** - Disconnect from current Redis instance

- **list_connections** - List all saved connections

- **switch_connection** - Switch to a different connection
  ```typescript
  {
    id: string  // Connection identifier to switch to
  }
  ```

#### Queue Management

- **list_queues** - List all queues in the current connection
  ```typescript
  {
    pattern?: string  // Queue name pattern (supports wildcards, default: "*")
  }
  ```

- **stats** - Get queue statistics
  ```typescript
  {
    queue: string  // Queue name
  }
  ```

- **pause_queue** - Pause queue processing
  ```typescript
  {
    queue: string  // Queue name
  }
  ```

- **resume_queue** - Resume queue processing
  ```typescript
  {
    queue: string  // Queue name
  }
  ```

- **drain_queue** - Remove all jobs from a queue
  ```typescript
  {
    queue: string  // Queue name
  }
  ```

- **clean_queue** - Clean jobs from queue
  ```typescript
  {
    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")
  }
  ```

#### Job Management

- **get_jobs** - Get jobs from queue by status
  ```typescript
  {
    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** - Get a specific job by ID
  ```typescript
  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  ```

- **add_job** - Add a new job to the queue
  ```typescript
  {
    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** - Remove a job from the queue
  ```typescript
  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  ```

- **retry_job** - Retry a failed job
  ```typescript
  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  ```

- **promote_job** - Promote a delayed job
  ```typescript
  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  ```

#### Job Logs

- **get_job_logs** - Get logs for a job
  ```typescript
  {
    queue: string,  // Queue name
    jobId: string   // Job ID
  }
  ```

- **add_job_log** - Add a log entry to a job
  ```typescript
  {
    queue: string,   // Queue name
    jobId: string,   // Job ID
    message: string  // Log message
  }
  ```

## BullMQ MCP Examples - How to Use BullMQ with Claude

### Connect to Redis and List Queues

```javascript
// 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 and Monitor a Job

```javascript
// Add a job with delay
await use_mcp_tool("bullmq", "add_job", {
  queue: "email-queue",
  name: "send-welcome-email",
  data: {
    to: "user@example.com",
    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"
});
```

### Queue Maintenance

```javascript
// 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"
});
```

### Advanced Job Management

```javascript
// 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
  });
}
```

## Getting Started with BullMQ MCP

### Prerequisites

1. **Redis Server**: Ensure Redis is running locally or accessible remotely
   ```bash
   # Check if Redis is running
   redis-cli ping
   # Should return: PONG
   ```

2. **Claude Desktop**: Install and configure Claude Desktop with the BullMQ MCP server

### Basic Workflow

1. **Connect to Redis**
   ```
   Connect to Redis using the bullmq tool with id "local"
   ```

2. **Explore Queues**
   ```
   List all queues and show me their statistics
   ```

3. **Monitor Jobs**
   ```
   Show me failed jobs in the email-queue
   ```

4. **Manage Jobs**
   ```
   Add a test job to my-queue with some sample data
   ```

## Common BullMQ MCP Use Cases

### 1. Monitoring Queue Health

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

### 2. Debugging Failed Jobs

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

### 3. Retrying Failed Jobs

```
Retry all failed jobs in the notification-queue
```

### 4. Queue Maintenance

```
Clean up completed jobs older than 24 hours from all queues
```

### 5. Managing Multiple Environments

```javascript
// 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"
});
```

## Testing the Connection

After configuring Claude Desktop, restart Claude and test the connection:

1. Open Claude Desktop
2. Start a new conversation
3. Test the MCP connection:

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

## Development

```bash
# 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
```

## Troubleshooting

### Connection Issues

- **Redis not running**: Ensure Redis is running on the specified host and port
  ```bash
  # Start Redis (macOS with Homebrew)
  brew services start redis

  # Start Redis (Linux)
  sudo systemctl start redis

  # Test connection
  redis-cli ping
  ```

- **Authentication failed**: Check that the Redis password (if any) is correct
- **Wrong database**: Ensure you're connecting to the correct Redis database number

### Common Errors

- **"No active connection"**: Use the `connect` tool first before other operations
- **"Job not found"**: Ensure the job ID exists in the specified queue
- **"Queue not found"**: The queue may not exist or have any jobs yet
- **Connection timeout**: Check firewall settings and Redis bind address

## Requirements

- Node.js 18+
- Redis server (standalone or cluster)

## Related Projects

- [`@adamhancock/bullmq-mcp`](https://github.com/adamhancock/bullmq-mcp) - The upstream package this is forked from
- [BullMQ](https://github.com/taskforcesh/bullmq) - The powerful Node.js job queue
- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol enabling AI-tool integration
- [Claude Desktop](https://claude.ai/download) - AI assistant with MCP support

## License

MIT