Sidekiq

You deploy a Sidekiq MCP server to give large language models a standardized way to interact with Sidekiq queues, statistics, and failed jobs. This enables you to monitor, inspect, and manage jobs from your AI workflows with consistent endpoints and real-time updates.

How to use

You access the MCP server through a remote endpoint to inspect queues, monitor statistics, and perform common job management actions. Use an MCP client or your integration to query tools such as sidekiq_stats, queue_details, failed_jobs, and stream_stats. You can also perform actions like retrying a failed job, rescheduling a scheduled job, or clearing a queue. Real-time updates can be streamed if you enable Server-Sent Events (SSE). Keep your authentication token ready and include it in your requests.

How to install

Prerequisites you need before installing the MCP server: Ruby and Bundler (since this is a Ruby gem-based MCP server). You should also have a working Rails or Rack-based application if you plan to integrate through Rails or Rack middleware.

# Add the gem to your Gemfile
gem 'sidekiq-mcp'

bundle install

Additional sections

Configuration and integration notes help you enable the MCP server and tailor access. The MCP server exposes a path (default: /sidekiq-mcp) where clients connect to request data and issue actions. You can enable Server-Sent Events for real-time updates and set an authentication token to secure access.

Rails integration example shows how to activate the MCP server in an initializer and enable the endpoint at the default path.

# config/initializers/sidekiq_mcp.rb
Sidekiq::Mcp.configure do |config|
  config.enabled = true
  config.path = "/sidekiq-mcp"
  config.auth_token = Rails.application.credentials.sidekiq_mcp_token
  config.sse_enabled = true # Enable Server-Sent Events for real-time updates
end

The MCP server will be available at the configured path (default: /sidekiq-mcp).

Manual setup for non-Rails apps

If you are not using Rails, you can add the middleware to your Rack stack to enable MCP access.

require 'sidekiq/mcp'

# Configure
Sidekiq::Mcp.configure do |config|
  config.auth_token = "your-secret-token"
end

# Add to your config.ru or middleware stack
use Sidekiq::Mcp::Middleware

Authentication

The MCP server supports two authentication methods for client requests. Use a Bearer token or HTTP Basic authentication. For Bearer authentication, include a header like Authorization: Bearer your-token. For HTTP Basic, provide any username with your token as the password.

Examples of client configuration (HTTP usage)

Clients can invoke the MCP endpoint using HTTP requests. For example, send a POST to the MCP URL with the appropriate authentication header.

Available tools

sidekiq_stats

Get general Sidekiq statistics such as processed, failed, busy, and enqueued counts.

job_class_stats

Breakdown of job counts, retries, and error rates by job class.

workers_count

Show how many workers are running and how many are currently busy.

queue_health

Assess whether queues are backed up or healthy using simple heuristics.

list_queues

List all queues with their sizes and latency.

queue_details

Get detailed information about a specific queue, including jobs.

busy_workers

List currently busy workers and the jobs they are executing.

failed_jobs

List failed jobs with error details for troubleshooting.

list_retry_jobs

List jobs in the retry set that will be retried.

list_scheduled_jobs

List jobs in the scheduled set.

dead_jobs

Show jobs in the dead set after exhausting retries.

job_details

Show arguments, error messages, and history for a job by JID.

retry_job

Retry a failed job by JID.

delete_failed_job

Delete a failed job by JID.

remove_job

Remove a job from any set (queue/schedule/retry/dead) by JID.

reschedule_job

Reschedule a job in the scheduled set to a new time.

kill_job

Move a job from retry or scheduled sets to the dead set.

clear_queue

Clear all jobs from a specific queue (destructive operation).

stream_stats

Start streaming real-time Sidekiq statistics via SSE.

process_set

Get detailed information about all Sidekiq processes and workers.