Sidekiq MCP

A Sidekiq plugin that provides an MCP (Model Context Protocol) server, enabling LLMs to interact with Sidekiq queues, statistics, and failed jobs through a standardized interface.

Available Tools

The MCP server provides the following tools:

Statistics & Monitoring

• sidekiq_stats - Get general Sidekiq statistics (processed, failed, busy, enqueued counts)
• job_class_stats - Breakdown of job counts, retries, and error rates by class
• workers_count - Show how many workers are running and busy
• queue_health - Heuristics on whether queues are backed up or healthy

Queue Inspection

• list_queues - List all queues with sizes and latency
• queue_details - Get detailed info about a specific queue including jobs
• busy_workers - List currently busy workers and their job details

Job Management

• failed_jobs - List failed jobs with error details
• list_retry_jobs - List jobs in the retry set (jobs that failed but will be retried)
• list_scheduled_jobs - List jobs in the scheduled set
• dead_jobs - Show jobs in the dead set (jobs that have exhausted all retries)
• job_details - Show args, error message, and history for a job by JID

Job Actions

• 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/scheduled set to the dead set
• clear_queue - Clear all jobs from a specific queue (destructive operation)

Real-time Monitoring

• stream_stats - Start streaming real-time Sidekiq statistics (use with SSE)
• process_set - Get detailed information about all Sidekiq processes/workers

Example Prompts

Once configured, you can ask your LLM:

• "What's the current status of Sidekiq?"
• "Show me the failed jobs and their error messages"
• "List all queues and their health status"
• "Which job classes have the highest error rates?"
• "Show me details for job abc123"
• "Retry the job with JID abc123"
• "What jobs are currently running?"
• "Are any queues backed up or unhealthy?"
• "How many workers are busy right now?"
• "Clear all jobs from the 'low_priority' queue"
• "Reschedule job abc123 to run tomorrow at 9 AM"
• "Move this failed job to the dead set"
• "Start streaming live stats updates"

Installation

Add this line to your application's Gemfile:

ruby gem 'sidekiq-mcp'

And then execute: bash bundle install

Usage

Rails Integration

The gem automatically integrates with Rails applications. Configure it in an initializer:

```ruby

config/initializers/sidekiq_mcp.rb

Sidekiq::Mcp.configure do |config| config.enabled = true config.path = "/sidekiq-mcp" config.authtoken = Rails.application.credentials.sidekiqmcptoken config.sseenabled = 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 (Non-Rails)

For non-Rails applications, add the middleware to your Rack stack:

```ruby 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:

1. Bearer Token: Include Authorization: Bearer your-token header
2. HTTP Basic Auth: Use any username with your token as the password

Example configuration for different MCP clients:

Claude Desktop

Add to your claude_desktop_config.json:

json { "mcpServers": { "sidekiq": { "command": "curl", "args": [ "-X", "POST", "-H", "Content-Type: application/json", "-H", "Authorization: Bearer your-secret-token", "http://localhost:3000/sidekiq-mcp" ] } } }

VS Code with Claude Extension

Configure in your VS Code settings:

json { "claude.mcpServers": { "sidekiq": { "url": "http://localhost:3000/sidekiq-mcp", "headers": { "Authorization": "Bearer your-secret-token" } } } }

Cursor

Add to your Cursor configuration:

json { "mcp": { "servers": { "sidekiq": { "command": ["curl"], "args": [ "-X", "POST", "-H", "Content-Type: application/json", "-H", "Authorization: Bearer your-secret-token", "http://localhost:3000/sidekiq-mcp" ] } } } }

Claude Code

Configure via CLI:

bash claude mcp add --transport http sidekiq-mcp-server http://localhost:3000/sidekiq-mcp

Or add to your MCP configuration:

json { "sidekiq-mcp": { "endpoint": "http://localhost:3000/sidekiq-mcp", "auth": { "type": "bearer", "token": "your-secret-token" } } }

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests.

The example/ directory contains a sample Rails application demonstrating the integration.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/andrew/sidekiq-mcp.

License

The gem is available as open source under the terms of the MIT License.