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 :)