MCP Server

bunqueue includes an MCP (Model Context Protocol) server that allows AI assistants like Claude to manage your job queues directly through natural language.

What is MCP?

MCP is an open protocol that enables AI assistants to interact with external tools and services. With bunqueue’s MCP server, you can:

Add and manage jobs using natural language
Monitor queue health and statistics
Configure cron jobs and rate limits
Debug failed jobs in the DLQ

Installation

The MCP server is included with bunqueue. No additional installation required.

bun add bunqueue

Configuration

Claude Desktop

Add bunqueue to your Claude Desktop configuration:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "bunqueue": {
      "command": "bunx",
      "args": ["bunqueue-mcp"]
    }
  }
}

{
  "mcpServers": {
    "bunqueue": {
      "command": "bunx",
      "args": ["bunqueue-mcp"]
    }
  }
}

{
  "mcpServers": {
    "bunqueue": {
      "command": "bunx",
      "args": ["bunqueue-mcp"]
    }
  }
}

Claude Code (CLI)

For Claude Code, add to your settings:

claude mcp add bunqueue -- bunx bunqueue-mcp

Or manually edit ~/.claude.json:

{
  "mcpServers": {
    "bunqueue": {
      "command": "bunx",
      "args": ["bunqueue-mcp"]
    }
  }
}

Available Tools

Job Operations

Tool	Description	Parameters
`bunqueue_add_job`	Add a job to a queue	`queue`, `name`, `data`*, `priority`, `delay`, `attempts`
`bunqueue_add_jobs_bulk`	Add multiple jobs	`queue`, `jobs` (array of `{name, data, priority, delay}`)
`bunqueue_get_job`	Get job by ID	`jobId`*
`bunqueue_cancel_job`	Cancel a job	`jobId`*
`bunqueue_update_progress`	Update progress	`jobId`, `progress` (0-100), `message`

Queue Control

Tool	Description	Parameters
`bunqueue_pause_queue`	Pause processing	`queue`*
`bunqueue_resume_queue`	Resume processing	`queue`*
`bunqueue_drain_queue`	Remove waiting jobs	`queue`*
`bunqueue_obliterate_queue`	Remove ALL data	`queue`*
`bunqueue_list_queues`	List all queues	-
`bunqueue_count_jobs`	Count jobs	`queue`*

Rate Limiting

Tool	Description	Parameters
`bunqueue_set_rate_limit`	Set jobs/second	`queue`, `limit`
`bunqueue_set_concurrency`	Set max concurrent	`queue`, `limit`

Dead Letter Queue

Tool	Description	Parameters
`bunqueue_get_dlq`	Get failed jobs	`queue`*, `limit`
`bunqueue_retry_dlq`	Retry from DLQ	`queue`*, `jobId` (optional)
`bunqueue_purge_dlq`	Clear DLQ	`queue`*

Cron Jobs

Tool	Description	Parameters
`bunqueue_add_cron`	Add recurring job	`name`, `queue`, `data`*, `schedule`, `repeatEvery`, `priority`
`bunqueue_list_crons`	List all crons	-
`bunqueue_delete_cron`	Delete cron	`name`*

Monitoring

Tool	Description	Parameters
`bunqueue_get_stats`	Queue statistics	-
`bunqueue_get_job_logs`	Job logs	`jobId`*
`bunqueue_add_job_log`	Add log entry	`jobId`, `message`, `level` (info/warn/error)

Example Prompts

Adding Jobs

"Add a job to the emails queue to send a welcome email to user@example.com"

"Add 100 jobs to the image-processing queue with URLs from this list..."

Queue Management

"Show me all queues and how many jobs are waiting"

"Pause the payments queue - we have an issue"

"Drain all waiting jobs from the notifications queue"

Monitoring & Debugging

"What are the current queue stats?"

"Show me failed jobs in the orders queue"

"Retry all jobs in the DLQ for the emails queue"

Cron Jobs

"Create a cron job that runs every hour to clean up old sessions"

"List all scheduled cron jobs"

"Delete the daily-backup cron job"

Complete Example

Here’s a full workflow using Claude with bunqueue MCP:

You: “I need to set up an email queue system”

Claude: Uses bunqueue_add_job to create test job

{
  "jobId": "019c0e14-19ed-7000-9c72-d81ae9d00938",
  "queue": "emails",
  "message": "Job added successfully"
}

You: “Add a cron job to send daily digest emails at 9 AM”

Claude: Uses bunqueue_add_cron

{
  "success": true,
  "name": "daily-digest",
  "queue": "emails",
  "nextRun": "2026-01-31T09:00:00.000Z"
}

You: “What’s the current status of all queues?”

Claude: Uses bunqueue_get_stats

{
  "waiting": 5,
  "active": 2,
  "completed": 143,
  "dlq": 1,
  "cronJobs": 1
}

Data Persistence

The MCP server uses SQLite for persistence. Default location:

./data/bunq.db

Configure with environment variable:

{
  "mcpServers": {
    "bunqueue": {
      "command": "bunx",
      "args": ["bunqueue-mcp"],
      "env": {
        "DATA_PATH": "/var/lib/bunqueue/queue.db"
      }
    }
  }
}

Processing Jobs

Run a worker alongside the MCP server:

import { Worker } from 'bunqueue/client';

new Worker('emails', async (job) => {
  const { to, subject, body } = job.data;

  await job.updateProgress(50, 'Sending email...');
  await sendEmail(to, subject, body);
  await job.log('Email sent successfully');

  return { sent: true, timestamp: Date.now() };
});

console.log('Worker started, processing emails queue...');

bun run worker.ts

Best Practices

Descriptive job names - Use names like send-welcome-email not job1
Set priorities - Critical jobs should have higher priority
Use delays - For rate-limited APIs, add delays between jobs
Monitor DLQ - Check failed jobs regularly
Cron for recurring - Don’t manually add repeated jobs

Troubleshooting

MCP server not connecting

# Verify installation
bunx bunqueue-mcp --help

# Check if Bun is in PATH
which bun

# Test manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | bunx bunqueue-mcp

Jobs stuck in waiting

Make sure a Worker is running:

# Check if worker is processing
bun run worker.ts

Data not persisting

Check file permissions:

ls -la ./data/
# Should show bunq.db with write permissions

Claude not seeing tools

Restart Claude Desktop/Code
Check config file syntax (valid JSON)
Verify path to bunqueue-mcp is correct