stuckbar

A straightforward CLI tool & MCP server for getting that annoying Windows taskbar unstuck.

When the Windows taskbar gets stuck (especially when configured to auto-hide), this utility provides a quick way to restart explorer.exe from the command line or via MCP tool calls, snapping the taskbar back to normal.

🪟 Windows Only: This tool is designed specifically for Windows and will not work on macOS or Linux.

Installation

Using cargo (recommended)

# Basic installation (CLI only)
cargo install stuckbar

# With MCP server support (STDIO transport)
cargo install stuckbar --features mcp

# With full MCP support (STDIO + HTTP transports)
cargo install stuckbar --features mcp-full

From source

git clone https://github.com/bkataru/stuckbar.git
cd stuckbar
cargo install --path .

# Or with MCP features
cargo install --path . --features mcp-full

Usage

Basic CLI Usage

# Restart explorer.exe (default action)
stuckbar

# Or explicitly use the restart command
stuckbar restart

# Just kill explorer.exe
stuckbar kill

# Just start explorer.exe
stuckbar start

# Show help
stuckbar --help

# Show version
stuckbar --version

Commands

MCP Server (AI Agent Integration)

Stuckbar can run as a Model Context Protocol (MCP) server, allowing AI agents to programmatically control Windows Explorer operations.

Features

When running as an MCP server, stuckbar exposes three tools:

Running the MCP Server

STDIO Transport (for direct process communication)

# Requires: cargo install stuckbar --features mcp
stuckbar serve --stdio

This is the recommended transport for most MCP clients like Claude Desktop.

HTTP Transport (SSE-based, for network communication)

# Requires: cargo install stuckbar --features mcp-full
stuckbar serve --http

# With custom host and port
stuckbar serve --http --host 0.0.0.0 --port 3000

The HTTP server uses Server-Sent Events (SSE) and exposes:

• SSE endpoint: http://<host>:<port>/sse
• Message endpoint: http://<host>:<port>/message

Configuration Examples

Claude Desktop

Add to your claude_desktop_config.json:

Windows:

{
  "mcpServers": {
    "stuckbar": {
      "command": "stuckbar",
      "args": ["serve", "--stdio"]
    }
  }
}

Or with full path:

{
  "mcpServers": {
    "stuckbar": {
      "command": "C:\\Users\\<username>\\.cargo\\bin\\stuckbar.exe",
      "args": ["serve", "--stdio"]
    }
  }
}

Other MCP Clients

For clients that support SSE transport:

stuckbar serve --http --port 8080
# Connect to: http://localhost:8080/sse

Feature Flags

Building from Source

# Clone the repository
git clone https://github.com/bkataru/stuckbar.git
cd stuckbar

# Build with default features
cargo build --release

# Build with MCP support
cargo build --release --features mcp-full

# Run tests
cargo test

# Run tests with all features
cargo test --all-features

How It Works

When the Windows taskbar becomes unresponsive or stuck (often happens with auto-hide enabled), the typical fix is to restart Windows Explorer. This tool automates that process by:

1. Kill: Forcefully terminating explorer.exe using taskkill /F /IM explorer.exe
2. Wait: Pausing briefly (500ms) to ensure the process is fully terminated
3. Start: Launching a new instance of explorer.exe

This restores the taskbar, desktop icons, and file explorer functionality.

Platform Support

This tool is Windows-only. Running on macOS or Linux will display an error message:

stuckbar is a Windows-only tool.
Current platform 'linux' is not supported.
This tool restarts explorer.exe which only exists on Windows.

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request :)