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 available tools are listed further down. Nothing leaves your Mac - see Trust & Privacy.

Related MCP server: chromectx

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. Access key - SupaSidebar writes a random key to ~/Library/Application Support/SupaSidebar/mcp-token that only your user can read. This server sends it with every request, and the app refuses anything without it, so websites you visit can't reach the bridge.

4. Zero telemetry - no analytics, no tracking, no usage reporting.

5. 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.4 requires SupaSidebar app 0.17.2 or later for its stable tools. SupaSidebar 1.7.1 and later only accept requests carrying the app's access key, so they need supasidebar-mcp@0.2.4 or later. The Auto-Close Never Close tools require an app build that includes the Never Close Rules beta feature. 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 every registered tool with its schema 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

Browse and search

Create and organize

Actions

Settings and shortcuts

Custom web search shortcuts

Air Traffic Control

Auto-Close Never Close Rules

Guide

License

MIT