SupaSidebar MCP Server

Give your AI assistant local access to your current open tabs, saved bookmarks, and recently opened links across every browser on your Mac. Nothing leaves your device.

Works with Claude Code, Claude Desktop, Cursor, Codex, VS Code Copilot, and any MCP-compatible client.

New to SupaSidebar? SupaSidebar is a free macOS app that brings an Arc-style sidebar to every browser - one place for your tabs, bookmarks, files, folders, and apps. This MCP server is the bridge that lets an AI agent drive it. You'll need the app installed and running (it's free to start), because every tool call runs locally against it.

Docs: docs.supasidebar.com/features/mcp

What you can do with it

Once it's connected, you talk to your AI assistant in plain language and it uses the tools below to act on your behalf. A few things people ask for:

Tame open tabs

"What do I have open right now? Save everything about the Q3 launch into a new 'Launch' space and close the noise."

(uses get_live_tabs, create_space, add_link)

Find that thing you saved

"Find the pricing page I bookmarked last week - I think it had 'billing' in the notes."

(uses search, list_recent)

Organize without clicking

"My unfiled links are a mess. Group them into folders by topic and move them there."

(uses list_links, create_folder, move_link)

Open things in the right place

"Open my three design links in Chrome's Work profile."

(uses list_browser_profiles, open_link)

Automate routing once, forever

"From now on, always open figma.com links in my browser's Design profile, and save any URL from my company domain into the 'Work' space."

(uses add_atc_rule)

Recall your day

"What did I open yesterday afternoon?"

(uses list_recent with date filters)

All 36 tools are listed further down. Nothing leaves your Mac - see Trust & Privacy.

How it works

AI Client --stdio--> MCP Server --localhost:9847--> SupaSidebar App
(Claude,              (this package,                 (your Mac,
 Cursor)               open source)                   your data)

The MCP server is a thin bridge. It translates AI tool calls into local HTTP requests to the SupaSidebar app running on your Mac. Your data never leaves your machine.

Trust & Privacy

1. Zero network requests - communicates only with 127.0.0.1 (localhost). The host is hardcoded and cannot be changed.
2. Zero data storage - no files written, no databases, no caches.
3. Zero telemetry - no analytics, no tracking, no usage reporting.
4. One runtime dependency - @modelcontextprotocol/sdk (the protocol library).

Prerequisites

New to SupaSidebar? Do these three steps in order. If you already run the app, skip to Setup.

1. Install and launch the SupaSidebar app

The MCP server is only a bridge - it needs the SupaSidebar Mac app running to do anything. Install it with Homebrew or a direct download:

• With Homebrew (one command, and brew upgrade keeps it current):

  brew install --cask supasidebar
  

  Cask on formulae.brew.sh
• Direct download - go to supasidebar.com, click Download For Free, then drag SupaSidebar into your Applications folder.

Then launch the app and leave it running - the server talks to its local bridge API at 127.0.0.1:9847, which is only available while the app is open.

Requirements: macOS 14 (Sonoma) or later. The download is free.

Version 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. Check your version in SupaSidebar → About, and update via SupaSidebar → Check for Updates if needed.

2. Grant macOS permissions

SupaSidebar needs two macOS permissions for the MCP tools to work end-to-end (especially anything touching browsers, tabs, or windows). Open the relevant pane in System Settings → Privacy & Security:

• Accessibility - required for window/sidebar control, global shortcuts, and tab management. Open: Privacy & Security → Accessibility
• Automation - required for browser integration (read live tabs, open URLs in specific browsers/profiles via AppleScript). Open: Privacy & Security → Automation

Make sure SupaSidebar is checked in both panes. If you grant a permission while the app is running, quit and relaunch SupaSidebar so it picks up the new permission.

3. Install Node.js 18 or newer

The server runs via npx, which comes with Node.js. Check whether you already have it:

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.

Once all three are done, continue to Setup.

Setup

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 session, /mcp shows 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.

Claude Desktop

Add to claude_desktop_config.json (Claude > Settings > Developer > Edit Config):

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

Cursor

Add to .cursor/mcp.json:

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

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 - see Troubleshooting below.

Troubleshooting

npx: command not found / command failed: npx You don't have Node installed. Either run brew install node, or download the LTS installer from nodejs.org/en/download if you don't use Homebrew. Restart your terminal and AI client afterwards.

Tools don't appear in Claude Code (mcp__supasidebar__* missing)

• Run claude mcp list - if supasidebar isn't there, registration failed. Re-run the claude mcp add command above.
• Confirm config is in ~/.claude.json, not ~/.claude/settings.json.
• Restart Claude Code after any MCP change - servers are spawned once at session start.
• For verbose handshake logs: claude --mcp-debug.

"Failed to connect to SupaSidebar" / fetch failed The MCP server can't reach the SupaSidebar app. Make sure SupaSidebar is running, then check the bridge:

curl http://127.0.0.1:9847/api/v1/health
# expected: {"app":"SupaSidebar","status":"ok",...}

"Failed to spawn process" (Cursor / version managers) If you use a Node version manager (fnm, nvm, volta), the AI client may not see your shell PATH. Replace the command/args with:

"command": "/bin/zsh",
"args": ["-lc", "npx -y supasidebar-mcp"]

Codex's /mcp panel shows fewer tools than expected Known display bug (openai/codex#17021) - Codex CLI's /mcp view under-reports MCP tools, even though all of them are registered and callable. To verify what's actually available, ask the agent directly with a prompt like:

List every SupaSidebar tool you have access to - there should be at least 35.

If Codex returns fewer, fall back to the MCP Inspector below for the ground truth.

See exactly which tools are exposed

Different clients show different views of MCP tools, and some (notably Codex) under-report what's actually registered. Use one of these to see the ground truth:

• Inside Claude Code: type /mcp - reliably lists each connected server and its tool count.
• Inside Codex: type /mcp (often under-reports - see entry above; prefer asking the agent or using the Inspector).
• Universal - MCP Inspector (works without any AI client; spins up a local web UI):

  npx @modelcontextprotocol/inspector npx -y supasidebar-mcp
  

  Open the printed URL in a browser, click "Connect", then "List Tools" - you'll see all 36 tools with their schemas and can test-call any of them. This is the fastest way to confirm whether a tool-count problem is in the server or in the client.

Available tools (36)

Browse and search

Tool	Description
search	Fuzzy search across all links by name, URL, notes, or tags
list_spaces	List all spaces (top-level collections)
list_links	List links in a space or folder, with names, URLs, tags, and notes
list_folders	List folders inside a space
list_recent	Recently opened links - paginate with limit/offset, filter with day/since/until
list_tags	List all tags, sorted by usage count
get_live_tabs	Get currently open browser tabs, optionally filtered by browser
list_browser_profiles	List browser profiles discovered by SupaSidebar (for use with open_link and ATC rules)
list_installed_browsers	List browsers actually installed on this machine (call before open_link if unsure)

Create and organize

Tool	Description
add_link	Save a new link (auto-fetches page title if name is omitted)
create_space	Create a new space
create_folder	Create a folder inside a space, optionally nested under a parent folder
move_link	Move a link to a different space or folder (pass targetFolderId: null for unfiled root)

Actions

Tool	Description
open_link	Open a URL in a specific browser, browser profile, or the default browser
switch_space	Switch to a different space
toggle_sidebar	Show or hide the sidebar
toggle_command_panel	Open or close the command panel
launch_sidebar	Start SupaSidebar if it's not running
get_visibility	Check if sidebar and command panel are visible (without changing state)
web_search	Search the web using Google, Bing, DuckDuckGo, Yahoo, Perplexity, Brave, Kagi, or any custom shortcut

Settings and shortcuts

Tool	Description
get_settings	Get all settings (grouped by category), or look up one setting by key or natural-language alias
update_setting	Change a setting (boolean, string, or number)
enable_feature	Apply a preset: Smart Attach, Independent Mode, Space Isolation, Minimal Sidebar, Full Featured
open_preferences	Open the Preferences window, optionally jumping to a specific tab
get_shortcuts	List all configurable keyboard shortcuts with current bindings
update_shortcut	Change a shortcut binding (requires at least one modifier)
clear_shortcut	Remove a shortcut binding

Custom web search shortcuts

Tool	Description
list_search_shortcuts	List all search engines and custom shortcuts with their keywords
add_search_shortcut	Create a custom search shortcut for a specific site
remove_search_shortcut	Delete a custom shortcut by keyword or ID

Air Traffic Control

Tool	Description
list_atc_rules	List all URL routing rules (evaluated top-to-bottom, first match wins)
add_atc_rule	Create a save rule (route saved links to a space) or open rule (open URLs in a specific browser/profile)
update_atc_rule	Update fields on an existing ATC rule
delete_atc_rule	Delete a rule by ID
reorder_atc_rules	Change rule priority order

Guide

Tool	Description
guide	Get a complete guide to all MCP capabilities, common requests, setting categories, and feature presets. Call this first if you're unsure which tool to use.

License

MIT