Sidekiq MCP

🚀 Sidekiq MCP

Sidekiq MCP is a Sidekiq plugin that offers an MCP (Model Context Protocol) server. This server enables LLMs to interact with Sidekiq queues, statistics, and failed jobs through a standardized interface, enhancing the management and monitoring capabilities of Sidekiq.

🚀 Quick Start

Sidekiq MCP simplifies the interaction between LLMs and Sidekiq. Once installed and configured, you can use it to manage and monitor Sidekiq queues, jobs, and statistics.

✨ Features

Available Tools

The MCP server provides a comprehensive set of tools for various Sidekiq management tasks:

Statistics & Monitoring

• sidekiq_stats: Retrieve general Sidekiq statistics, including processed, failed, busy, and enqueued job counts.
• job_class_stats: Get a breakdown of job counts, retries, and error rates by job class.
• workers_count: Show the number of running and busy workers.
• queue_health: Assess whether queues are backed up or healthy.

Queue Inspection

• list_queues: List all queues along with their sizes and latency.
• queue_details: Obtain detailed information about a specific queue, including its jobs.
• busy_workers: List currently busy workers and their associated 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: Display 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 the retry/scheduled set to the dead set.
• clear_queue: Clear all jobs from a specific queue (a 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 use the following prompts with 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 the following line to your application's Gemfile:

gem 'sidekiq-mcp'

Then, execute the following command:

bundle install

💻 Usage Examples

Basic Usage

Rails Integration

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

# 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 (Non-Rails)

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

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

Advanced Usage

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:

{
  "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:

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

Cursor

Add to your Cursor configuration:

{
  "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:

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

Or add to your MCP configuration:

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

🔧 Technical Details

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.

📄 License

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