bunqueue

Name: bunqueue
Author: Egeo Minotti

Run and manage bunqueue job queues, cron schedules and dead letter queues from an AI client

Official · Egeo Minotti TypeScript Local · stdio Developer tools DevOps and monitoring

GitHub npm Website

77 popularity score ★ 591 ↓ 7.4k/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal

bun add -g bunqueue @modelcontextprotocol/sdk

Claude CodeTerminal

claude mcp add bunqueue -- bunx --package bunqueue bunqueue-mcp

Claude Desktopclaude_desktop_config.json

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

Cursor~/.cursor/mcp.json

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

VS Code.vscode/mcp.json

{
  "servers": {
    "bunqueue": {
      "type": "stdio",
      "command": "bunx",
      "args": [
        "--package",
        "bunqueue",
        "bunqueue-mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.bunqueue]
command = "bunx"
args = ["--package", "bunqueue", "bunqueue-mcp"]

Gemini CLITerminal

gemini mcp add --scope user bunqueue bunx -- --package bunqueue bunqueue-mcp

Settings 12

Set together: agent features
`BUNQUEUE_MCP_PROFILE`	Optional: agent fills in dynamic toolsets and destructive-call confirmation when those two are unset; any other value stops startup.
Set together: embedded
`DATA_PATH`	Optional: SQLite file to keep jobs in embedded mode; in memory when unset (BUNQUEUE_DATA_PATH and BQ_DATA_PATH take priority).
Set together: tcp
`BUNQUEUE_MODE`	Optional: embedded or tcp to work on a running bunqueue server. Default `embedded`.
`BUNQUEUE_HOST`	Optional: bunqueue server host in TCP mode. Default `localhost`.
`BUNQUEUE_PORT`	Optional: bunqueue server TCP port; an invalid value stops startup. Default `6789`.
`BUNQUEUE_TOKEN` secret	Optional: Auth token of the bunqueue server in TCP mode.
Set together: http
`BUNQUEUE_MCP_TRANSPORT`	Optional: stdio or http (Streamable HTTP on 127.0.0.1:6791/mcp by default). Default `stdio`.
`BUNQUEUE_MCP_HTTP_TOKEN` secret	Optional: Comma-separated bearer tokens for the HTTP transport; needed when BUNQUEUE_MCP_HTTP_HOST is not loopback.
`BUNQUEUE_MCP_TOOLSETS`	Optional: all, a list of tool groups, or dynamic (optionally with groups to preload) to load groups on demand. Default `all`.
`BUNQUEUE_MCP_CONFIRM`	Optional: destructive to require confirmation before nine destructive tools (ten with workflow tools); off when unset.
`BUNQUEUE_MCP_DECISION_PROVIDER`	Optional: typesafe, cloudflare or systemone; needs BUNQUEUE_MCP_DECISION_API_KEY (typesafe, cloudflare) or _MODEL and _URL (systemone). For decision model.
`BUNQUEUE_MCP_WORKFLOW_DB`	Optional: Path of an existing workflow Engine dataPath file; turns on the workflow tools. For workflow tools.

What it does

bunqueue is a job queue for the Bun runtime, and its npm package carries a second program, bunqueue-mcp, that exposes the queue to an MCP client. Through it an assistant can add jobs and flows, schedule cron jobs, pull and acknowledge work by hand, set rate and concurrency limits, inspect and retry failed jobs in the dead letter queue, manage webhooks, and read statistics, queue diagnoses or Prometheus metrics.

It runs in one of two modes. By default the queue lives inside the MCP process itself, in memory, or in a SQLite file when DATA_PATH is set. With BUNQUEUE_MODE=tcp it connects instead to a bunqueue server you already run (port 6789 by default) and works on the same queues your workers use, whether that server keeps them in SQLite or PostgreSQL. Since an assistant cannot run worker code, the register_handler tool lets it point a queue at a URL; the MCP process then makes that HTTP call for every job and stores the response as the result.

It speaks stdio by default and can serve Streamable HTTP for several clients at once. Opt-in settings change how the tools behave: tool groups loaded on demand to save context, a confirmation step before destructive calls, and an outside decision model that can veto destructive requests. The README's install command now sets BUNQUEUE_MCP_PROFILE=agent; per src/mcp/agentProfile.ts at v2.9.20 that preset only fills in BUNQUEUE_MCP_TOOLSETS=dynamic and BUNQUEUE_MCP_CONFIRM=destructive when those are unset, and any other value of it stops the server.

The docs count 79 primary tools; the tool policy file at v2.9.20 (src/mcp/toolPolicy.ts) maps 82, the extra three being workflow tools that appear only when BUNQUEUE_MCP_WORKFLOW_DB is set, plus the dynamic-discovery tools counted apart. Of the 82 it marks 35 read-only, so most tools change queue state. It also serves 5 read-only resources and 3 prompts.

What it needs

Runtime	Bun 1.4+
Runs on	macOS, Windows, Linux
Also	@modelcontextprotocol/sdk installed next to bunqueue A running bunqueue server for TCP mode

The MCP server and embedded mode run only on Bun 1.4.0 or newer. Since v2.8.1 the MCP SDK is an optional peer dependency that bunqueue does not install, so run `bun add -g bunqueue @modelcontextprotocol/sdk` first. TCP mode needs a running bunqueue server and its auth token if it has one. Workflow tools need an existing Engine dataPath file on the same machine; signalling runs also needs TCP mode. `bunqueue-mcp --doctor --json` checks the settings before connecting.

Limits

Limit In embedded mode without DATA_PATH, jobs live in memory and are lost when the client session ends
Not covered An assistant cannot run worker code; jobs stay waiting unless an HTTP handler or a Worker processes them
Limit HTTP handlers live in the MCP process, so under stdio they stop with the session and must be registered again
Rate limit Handler calls time out after 30 s by default, settable from 1 to 120 s
Size cap HTTP transport: 100 sessions by default, 4 MiB request bodies, sessions held in memory and closed after 30 idle minutes
Limit The HTTP transport has no built-in TLS; the docs say to put a reverse proxy in front
Not covered bunqueue_signal_workflow is left out in embedded mode; the workflow runs can still be listed
Limit The docs warn that SQLite on a network filesystem is not safe
Platform The MCP server runs only on Bun, not Node

In the default embedded mode without DATA_PATH, jobs live in memory and are lost when the client session ends. HTTP handlers live in the MCP process, so under stdio they stop with the session and must be registered again. An assistant cannot run worker code itself; jobs stay waiting unless a handler or a Worker processes them. Handler calls time out after 30 s by default (1 to 120 s). The HTTP transport has no TLS, holds sessions in memory (lost on restart, closed after 30 idle minutes), allows 100 sessions and 4 MiB request bodies. bunqueue_signal_workflow is left out in embedded mode. The docs warn that SQLite on a network filesystem is not safe.

Who it suits

Suits teams already running bunqueue on Bun who want an assistant to inspect queues, retry failures and adjust schedules or limits on a live server through TCP mode, and anyone trying the queue locally with no setup. Since most tools write and some delete jobs for good, a shared or production server is better run with BUNQUEUE_MCP_PROFILE=agent or BUNQUEUE_MCP_CONFIRM=destructive and a narrowed BUNQUEUE_MCP_TOOLSETS list. It needs Bun on the machine running it, and works only on bunqueue's own queues.

Tools 60 of 82

27 only read, 24 change things, 9 can delete or overwrite.

bunqueue_get_capabilities: Report the running server's effective mode, toolsets and settings
bunqueue_add_job changes: Add one job to a queue, with priority, delay, retries, timeout and dedup options
bunqueue_add_jobs_bulk changes: Add many jobs to a queue in one call
bunqueue_get_job: Show a job with its data, state and the options it carries
bunqueue_get_job_state: Return the current state of a job
bunqueue_get_job_result: Return the result a finished job produced
bunqueue_wait_for_job: Wait until a job finishes and return it
bunqueue_observe_job: Take a snapshot of a job, or poll it read-only for up to 30 s, until it settles
bunqueue_get_job_logs: Read the log lines attached to a job
bunqueue_clear_job_logs deletes: Delete a job's log lines
bunqueue_cancel_job deletes: Cancel and remove a job
bunqueue_discard_job changes: Move a job to the dead letter queue, where it can be retried
bunqueue_promote_job changes: Make a delayed job ready to run now
bunqueue_update_job_data deletes: Replace the data payload of a job
bunqueue_change_job_priority changes: Change a job's priority
bunqueue_move_to_delayed changes: Push a job back into the delayed set
bunqueue_pull_job changes: Take the next job from a queue to process by hand, optionally locked to an owner
bunqueue_pull_job_batch changes: Take several jobs from a queue at once
bunqueue_ack_job changes: Mark a pulled job completed with its result
bunqueue_fail_job changes: Mark a pulled job failed, or send it straight to the dead letter queue
bunqueue_job_heartbeat changes: Renew the lock on a job being processed
bunqueue_list_queues: List the queues that exist
bunqueue_count_jobs: Count the jobs in a queue
bunqueue_get_jobs: List jobs in a queue, filtered by state
bunqueue_list_jobs_page: Page through a queue's jobs in bounded pages, payloads left out by default
bunqueue_get_job_counts: Return job counts per state for a queue
bunqueue_is_paused: Tell whether a queue is paused
bunqueue_pause_queue changes: Pause processing on a queue
bunqueue_resume_queue changes: Resume a paused queue
bunqueue_drain_queue deletes: Remove all waiting jobs from a queue
bunqueue_clean_queue deletes: Remove old jobs in a given state from a queue
bunqueue_obliterate_queue deletes: Delete a queue and every job in it
bunqueue_get_dlq: List dead letter entries with failure reason and recent attempts
bunqueue_get_dlq_stats: Summarise the dead letter queue by reason and age
bunqueue_retry_dlq changes: Send dead letter entries back to the queue
bunqueue_purge_dlq deletes: Delete a queue's dead letter entries
bunqueue_retry_completed changes: Run one completed job, or all of a queue's, again
bunqueue_add_cron changes: Create a repeating schedule by cron expression or interval, with time zone
bunqueue_list_crons: List cron schedules and their next runs
bunqueue_get_cron: Show one cron schedule
bunqueue_delete_cron deletes: Remove a cron schedule
bunqueue_set_rate_limit changes: Cap how many jobs a queue starts per time window
bunqueue_set_concurrency changes: Cap how many jobs of a queue run at once
bunqueue_get_queue_limits: Read a queue's rate and concurrency limits and whether they hold jobs back
bunqueue_add_flow changes: Add a parent job with child jobs
bunqueue_add_flow_chain changes: Add jobs that run one after another
bunqueue_get_flow: Show a flow's tree of parent and child jobs
bunqueue_get_children_values: Collect the results of a parent job's children
bunqueue_register_handler changes: Attach a URL to a queue so every job there is sent to it as an HTTP call
bunqueue_list_handlers: List the HTTP handlers registered in this process
bunqueue_register_worker changes: Register a worker record with the queue
bunqueue_list_workers: List registered workers
bunqueue_add_webhook changes: Register a URL that is called on job events
bunqueue_list_webhooks: List the webhooks set up
bunqueue_remove_webhook deletes: Delete a webhook
bunqueue_get_stats: Return overall queue statistics
bunqueue_diagnose_queue: Look into why a queue's jobs are not moving
bunqueue_get_prometheus_metrics: Return metrics in Prometheus text format
bunqueue_list_workflow_executions: List workflow engine runs (only with BUNQUEUE_MCP_WORKFLOW_DB set)
bunqueue_signal_workflow changes: Send an approval signal to a waiting workflow run; the first signal wins and cannot be undone

Resources 5

bunqueue://stats: Overall queue statistics
bunqueue://queues: The queues and their counts
bunqueue://crons: Cron schedules
bunqueue://workers: Registered workers
bunqueue://webhooks: Configured webhooks

Prompts 3

bunqueue_health_report: Build a health report of the queues
bunqueue_debug_queue: Work out why jobs are stuck in a queue
bunqueue_incident_response: Walk through responding to a queue incident

Popularity

77 popularity score, on our list (the bar is 36)

★ 591 ↓ 7.4k/wk

GitHub stars	591	33.3 points
Stars in 30 days	+9	5 points
npm downloads, last week	7,356	30.9 points
Official server	Yes	8 points

Measured 2026-11-08. How the score works.

Where it is published

Code	egeominotti/bunqueue ★ 591
npm	bunqueue 2.9.21, 2026-10-31

What it can reach

Runs	On your machine
Reaches	A database, The internet
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT (npm)
Usage data	Only if you turn it on (`BUNQUEUE_CLOUD_URL`) In embedded mode with BUNQUEUE_CLOUD_URL set, a Cloud agent sends records and a summary of MCP tool operations to that URL
Last code change	2026-11-01

Runs on your machine. In embedded mode it writes only its own in-memory queue or the SQLite file named in DATA_PATH; in TCP mode it can change or delete jobs and queues on the bunqueue server it connects to, using BUNQUEUE_TOKEN. register_handler and add_webhook make the process send HTTP requests to any URL the assistant gives, with job data as the body for POST and PUT. Tools such as obliterate_queue, drain_queue and purge_dlq delete data permanently; confirmation before nine of them is off unless BUNQUEUE_MCP_CONFIRM=destructive or BUNQUEUE_MCP_PROFILE=agent is set. A decision provider, when set, sends request text and queue and job names to that hosted service. The HTTP transport binds to 127.0.0.1 and refuses other addresses without a token.

Over time

GitHub stars 591 +9 (+2 %)

591582

9 Oct 20268 Nov 2026

npm downloads a week 7.4k +4.8k (+186 %)

7.9k700

9 Feb 20268 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 77 +13 (+20 %)

7764

9 Oct 20268 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-26.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![bunqueue on EveryMCPServer](https://everymcpserver.com/badge/bunqueue.svg)](https://everymcpserver.com/servers/bunqueue)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 60 of 82

Resources 5

Prompts 3

Similar servers

Ruflo

Claudish

ai-rulez

Backstage MCP Actions

AgentRQ

Sentry MCP