SupaSidebar MCP

Control SupaSidebar from AI assistants like Claude using the Model Context Protocol (MCP) - search your sidebar, switch spaces, open links, and configure settings hands-free.

GitHub: github.com/auspy/supasidebar-mcp 

How it works

MCP (Model Context Protocol) is an open standard that lets AI assistants interact with external tools. SupaSidebar exposes 36 tools via its MCP server, so any compatible AI assistant can read and control your sidebar programmatically.

Available actions

Browse and search

Read your sidebar data - find links, browse spaces, check open tabs, see recent activity, and inspect browser availability.

Actions

Control SupaSidebar - open links, switch spaces, toggle visibility, and search the web.

Settings and configuration

Read and change SupaSidebar settings, apply feature presets, and open Preferences.

Keyboard shortcuts

View and rebind SupaSidebar’s keyboard shortcuts.

Create and organize

Add new content and reorganize your sidebar - create spaces, folders, save links, and move items between spaces.

Air Traffic Control

Create and manage URL routing rules. Save rules route saved links into spaces. Open rules route matching URLs to specific browsers or browser profiles.

Custom web search shortcuts

Create shortcuts to search specific websites directly from SupaSidebar. For example, add a “yo” shortcut for YouTube so you can search YouTube without opening it first.

Example: To add a YouTube search shortcut, provide keyword yo, name YouTube, and search URL https://www.youtube.com/results?search_query=. Then ask your AI assistant to “search YouTube for lofi music” and it opens the results directly.

Guide

Prerequisites

You need Node.js 18 or newer (which provides npx). Check with:

node --version    # should print v18.x or higher
npx --version     # should print a version number, not "command not found"

If npx isn’t found, install Node. Pick whichever you prefer:

• With Homebrew (easiest if you already have brew):

  brew install node

• Without Homebrew - download the LTS installer from nodejs.org/en/download  and run it. The macOS .pkg installer puts node and npx on your PATH automatically; just restart your terminal afterwards.

The SupaSidebar app must be running - the MCP server talks to its local bridge API at 127.0.0.1:9847.

Check the bridge from inside the app

Open Preferences - AI to see the local MCP bridge status, the endpoint URL, a link to this setup guide, and a Restart button. Use it to confirm the bridge is up before troubleshooting your AI client - if the panel shows the bridge as offline, restart it from there first.

Compatibility: supasidebar-mcp@0.2.3 requires SupaSidebar app 0.17.2 or later. Older app versions are missing bridge endpoints used by some of the 36 tools.

macOS permissions

SupaSidebar needs Accessibility and Automation permissions for the MCP tools to work end-to-end - browser integration, tab access, window control, and global shortcuts all rely on these.

See the full setup guide: Setting up permissions

Setup with Claude Code

The recommended way - register at user scope so it’s available in every project:

claude mcp add -s user supasidebar -- npx -y supasidebar-mcp

Verify it registered:

claude mcp list
# expected: supasidebar    ✓ Connected

Inside a Claude Code session, type /mcp to see connected servers and tool counts.

Just for one project? Drop -s user:

claude mcp add supasidebar -- npx -y supasidebar-mcp

⚠️ Do not put MCP config in ~/.claude/settings.json. That file is for hooks, permissions, and env vars only - Claude Code silently ignores unknown keys there, so the server appears to “register” but no tools will load. The correct location is ~/.claude.json under mcpServers (which claude mcp add writes to automatically).

Prefer to hand-edit? Add to ~/.claude.json (note: .claude.json, not .claude/settings.json):

{
  "mcpServers": {
    "supasidebar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "supasidebar-mcp"]
    }
  }
}

Restart Claude Code after editing.

Setup with Claude Desktop

1. Open Claude Desktop settings (Claude → Settings → Developer → Edit Config)
2. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "supasidebar": {
      "command": "npx",
      "args": ["-y", "supasidebar-mcp"]
    }
  }
}

3. Restart Claude Desktop. You can now ask Claude to search your sidebar, switch spaces, open links, and more.

Setup with Cursor

1. Open Cursor settings (Cursor → Settings → MCP)
2. Click Add new MCP server
3. Set the command to npx -y supasidebar-mcp
4. Save and restart Cursor

Setup with Codex

1. Make sure Codex CLI is installed and SupaSidebar is running
2. Register the MCP server:

   codex mcp add supasidebar -- npx -y supasidebar-mcp

3. Verify with codex mcp list and codex mcp get supasidebar
4. Inside a Codex session, ask the agent to “list every SupaSidebar tool you have access to - there should be at least 35” to confirm all tools are wired up. Codex’s /mcp panel sometimes under-reports, but the tools are still callable.

Privacy

MCP tool calls are counted in the app’s anonymous usage stats alongside crash reports. Disable in Preferences → About → Share Usage and Crash Reports.

Troubleshooting

Setup issues - tools not appearing, can’t reach SupaSidebar, npx not found, Codex showing fewer tools than expected, version-manager spawn errors - are covered on a dedicated page:

MCP Setup Troubleshooting →

Tips

• Ask your AI assistant to “search my sidebar for [topic]” to find links across all spaces
• Say “save this link to my Work space” to add links without opening the sidebar
• Use “switch to my Work space” to change context without touching the keyboard
• Combine with Spaces to organize by project, then let your AI switch context for you
• Use feature presets like “enable minimal sidebar” to quickly reconfigure SupaSidebar for different workflows
• MCP works alongside keyboard shortcuts - use whichever is faster for the task
• See the full documentation and source code on GitHub