BullMQ MCP

BullMQ MCP 服务 - 用于 BullMQ 队列管理的模型上下文协议

一个功能全面的 BullMQ MCP（模型上下文协议）服务，用于管理基于 Redis 的 BullMQ 任务队列。此 BullMQ MCP 集成支持 Claude Desktop 和其他 AI 助手通过自然语言与 BullMQ 队列交互、监控任务状态、管理工作进程并执行队列操作。

关键词：BullMQ MCP、BullMQ 模型上下文协议、BullMQ Claude 集成、BullMQ AI 助手、BullMQ 队列管理、Redis 队列 MCP

功能

• 🔌 连接管理：连接多个 Redis 实例并在它们之间切换
• 📊 队列操作：列出、暂停、恢复、清空和清理队列
• ⚙️ 任务管理：添加、移除、重试和提升任务
• 📈 任务监控：查看任务详情、日志和统计信息
• 🧹 批量操作：按状态清理任务，并可配置限制
• 🔄 多连接：管理不同的 Redis 实例（开发、预发布、生产）
• 📝 任务日志：为任务添加和查看自定义日志条目
• 🎯 灵活的状态筛选：按各种状态查询任务（active、waiting、completed、failed、delayed）

安装 - BullMQ MCP 设置

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 BullMQ 队列管理服务：

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，可通过一条命令添加 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 时，请使用 host.docker.internal 而非 localhost，以连接在主机上运行的 Redis。

手动配置

若要手动配置 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 时，请使用 host.docker.internal 而非 localhost，以连接在主机上运行的 Redis。

可用的 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 检测）， localhost 将自动重定向到 host.docker.internal，以连接主机上的 Redis。

• 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：安装并配置 Claude Desktop 和 BullMQ MCP 服务

基本工作流

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 数据库编号

常见错误

• “No active connection”：在执行其他操作前，先使用 connect 工具

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

• “Job not found”：确保指定队列中存在该作业 ID

  List jobs in the queue first to see available job IDs
  

• “Queue not found”：该队列可能不存在或尚无任何作业

  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 服务贡献！欢迎提交问题或拉取请求，以改进此集成。

支持

关于以下内容的问题：

• BullMQ MCP 服务：GitHub Issues
• 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 服务