MCP Server

Connect any agent to your Stash captures.macOS only

Stash ships a local Model Context Protocol server. Any MCP-compatible agent — Claude Code, Claude Desktop, Cursor, Codex CLI, Continue, Windsurf, Zed, Warp, Cline — can read your screenshots, annotations, and video bundles directly. No cloud, no upload, no OCR fallback. Data never leaves your Mac.

What you get: the agent sees the exact app, window, selected text, git branch, and accessibility tree behind every screenshot — plus whatever you drew on it. No more "which file is that?" or "what app is this?".

Key takeaways

One-line install

Install Stash, launch it once to grant permissions, then run: 

curl -fsSL https://yourstash.ai/install-claude.sh | bash

The bridge binary ships bundled inside Stash.app at /Applications/Stash.app/Contents/Helpers/stash-mcp — pre-signed under Stash's Apple team with Hardened Runtime, so there is no compile step and no Apple Developer certificate required. The installer verifies the bundled helper exists and is validly signed, merges a stash server entry pointing at that path into Claude Code, Claude Desktop, and Cursor if any are installed, and — when Claude Code is present — drops the Stash skill into ~/.claude/skills/stash/ so the agent knows Stash's trigger phrases. Safe to re-run. Nothing leaves your machine.

When it finishes, ask your client "what was my last Stash capture?" — if Stash answers with real capture details (app, window, time), you're done. For Claude Code, run /mcp reload in any active session or start a new one.

Using Codex CLI, Continue, Windsurf, Zed, Warp, or Cline? See manual setup below — the installer doesn't auto-configure those clients.

Prefer a download?

For Claude Desktop, the native install flow is a drag-drop skill package:

Download Stash skill package

For Claude Desktop, unzip and point its extensions panel at the folder. For Claude Code, unzip to ~/.claude/skills/stash/ so the stash skill appears in /skills. Either way you'll still need to register the bridge with your client — point its command at the bundled binary at /Applications/Stash.app/Contents/Helpers/stash-mcp (see manual setup below). The skill package only carries recognition rules and documentation; the bridge itself ships inside Stash.app.

Manual setup

If you'd rather wire things up yourself — or you use a client the installer doesn't auto-configure — here's the per-client setup.

About paths: every snippet below uses the absolute path to the bridge bundled inside Stash.app — /Applications/Stash.app/Contents/Helpers/stash-mcp. It's absolute on purpose: GUI apps (Claude Desktop, Cursor, Windsurf, Warp) launched from Finder or the Dock don't inherit your shell's PATH, and CLI clients may not run in your login shell either. If you installed Stash somewhere other than /Applications, adjust the prefix accordingly.

Locate the bundled bridge

The bridge binary ships inside Stash.app — there is nothing to compile and no Apple Developer certificate required. It lives at: 

/Applications/Stash.app/Contents/Helpers/stash-mcp

It is pre-signed as part of Stash.app under Stash's Apple team (VJMJQKCRMC) with Hardened Runtime — and that team is already in Stash's built-in MCP peer-auth allowlist, so it connects with no extra setup. Confirm it's present and validly signed: 

codesign --verify --verbose /Applications/Stash.app/Contents/Helpers/stash-mcp

Register the MCP server with your client

Auto-configured by installer
Manual setup

Use the claude CLI:

claude mcp add stash -s user -- /Applications/Stash.app/Contents/Helpers/stash-mcp

Then drop the skill so Claude knows Stash's trigger phrases:

mkdir -p ~/.claude/skills/stash
curl -fsSL https://yourstash.ai/releases/stash-claude-skill.zip -o /tmp/stash-skill.zip
unzip -o /tmp/stash-skill.zip -d ~/.claude/skills/stash

Verify with claude mcp list — you should see stash … ✓ Connected. If you have a claude session open, run /mcp reload or start a new session for the tools to appear.

For project scope instead of user, drop -s user and run from inside the project root — it'll write to .mcp.json for that project. The CLI persists user-scope entries to ~/.claude.json.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "stash": {
      "command": "/Applications/Stash.app/Contents/Helpers/stash-mcp"
    }
  }
}

Quit Claude Desktop with ⌘Q and relaunch (closing the window isn't enough). The MCP indicator appears in the bottom-right of the message box — click it to see Stash's tools.

If the indicator never appears, tail ~/Library/Logs/Claude/mcp.log and mcp-server-stash.log. Most failures are missing-binary or relative-path issues — Claude Desktop requires absolute paths in command.

Edit ~/.cursor/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "stash": {
      "command": "/Applications/Stash.app/Contents/Helpers/stash-mcp"
    }
  }
}

Restart Cursor. Open Settings (⌘⇧J) → MCP & Integrations — Stash appears with a status dot, tool count, and an enable toggle. Tools then become available to Cursor's Composer/Agent (⌘I).

Project-scoped alternative: .cursor/mcp.json in your repo root. A green status dot confirms connection; click the row for tool details and per-tool toggles.

Edit ~/.codex/config.toml — add the table at the end of the file:

[mcp_servers.stash]
command = "/Applications/Stash.app/Contents/Helpers/stash-mcp"
args = []

Restart any active codex session, then run codex mcp list — stash should appear in the list.

Codex auto-loads servers on startup — no separate enable step. Verified locally.

Create .continue/mcpServers/stash.yaml in your workspace:

name: stash
type: stdio
command: /Applications/Stash.app/Contents/Helpers/stash-mcp

In Continue's chat, switch the mode dropdown to Agent — MCP tools only run in Agent mode.

Continue picks up .continue/mcpServers/ files automatically. If stash doesn't appear, reload the Continue extension (Command Palette → "Continue: Reload"). Based on continue.dev docs as of April 2026 — report issues.

Click the MCPs icon in the top-right of the Cascade panel, or edit ~/.codeium/windsurf/mcp_config.json directly:

{
  "mcpServers": {
    "stash": {
      "command": "/Applications/Stash.app/Contents/Helpers/stash-mcp"
    }
  }
}

Open the MCP servers panel in Cascade — stash should appear with its tools listed. Restart Windsurf if it doesn't.

Based on Windsurf Cascade MCP docs as of April 2026 — report issues.

Edit ~/.config/zed/settings.json — note the key is context_servers, not mcpServers (Zed's older terminology):

{
  "context_servers": {
    "stash": {
      "command": "/Applications/Stash.app/Contents/Helpers/stash-mcp"
    }
  }
}

Zed picks up changes without a full restart. If stash doesn't appear, reopen the Agent Panel (top-right menu → settings). A green dot next to the server name confirms it's active.

Based on Zed MCP docs as of April 2026 — report issues.

Open Warp Settings → Agents → Warp Agent → Manage MCP servers. Click + Add and choose CLI Server (Command). Fill in the form:

  • Name: stash
  • Command: /Applications/Stash.app/Contents/Helpers/stash-mcp
  • Arguments / Environment / Working Directory: leave empty

Save and click Start on the server row. No Warp restart needed — Stash's tools appear in the next Agent message.

A failed start surfaces inline error text on the server row. Based on Warp MCP docs as of April 2026.

In VS Code or Cursor, click Cline's MCP Servers icon → Configure tab → Edit Configuration. Paste:

{
  "mcpServers": {
    "stash": {
      "command": "/Applications/Stash.app/Contents/Helpers/stash-mcp",
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

No reload required — Cline auto-detects the config change. The Installed tab shows stash with a green dot when connected and lists its tools.

Direct file edit (advanced): the config lives at ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (substitute Cursor for Code if you use Cursor). Based on Cline docs as of April 2026.

Aider: No native MCP support yet — track aider#4506. We'll add a tab here once Aider ships first-class MCP.
Architecture: the skill package carries the protocol-stable stuff — how to recognize a Stash banner, filename, or XMP tag, plus offline fallback rules. The MCP server carries the release-variable stuff — current tool list, trigger phrases, response field layouts. When you update Stash via Sparkle, clients pick up the fresh guidance on next connect without you reinstalling anything.

What Claude can do with Stash

Privacy

The MCP socket is bound to a UNIX domain socket under your user account — local only, not networked. Stash rejects unsigned / unknown peers by default via codesign team-ID allowlist; the bundled bridge is signed under Stash's team, so it's trusted out of the box. Sensitive fields (selected text, file paths, git branches, terminal CWD, a11y tree) purge 24 hours after capture by default. Screenshots and basic metadata follow your normal history retention. Stash servers never see capture data — ever.

One honest caveat on peer auth: team-ID allowlisting is a speedbump, not a hard boundary. Because the bridge is a pure relay, any local process can launch the trusted bridge and drive it — a confused-deputy weakness. It stops other signed apps from connecting to the socket directly; it does not stop arbitrary same-user code. A capability-token handshake is the planned future replacement. The mcpAllowUnsignedClients toggle (Settings → Privacy) removes the check entirely and lets any unsigned local process connect — keep it off unless you're knowingly testing locally.

For the full protocol spec, see yourstash.ai/protocol or fetch the machine-readable version at yourstash.ai/llms.txt.

Frequently asked questions

Which MCP clients does Stash support?

The one-line installer auto-configures Claude Code, Claude Desktop, and Cursor — the three clients with the largest install bases. Stash also works with Codex CLI, Continue, Windsurf, Zed, Warp, and Cline via copy-paste config (see manual setup). Aider doesn't support MCP natively yet — tracking aider#4506. All clients connect to the same bridge binary, which ships bundled inside Stash.app at /Applications/Stash.app/Contents/Helpers/stash-mcp. macOS only — Stash itself is a Mac app.

Does Stash send my screenshots or capture data to the cloud?

No. The MCP server runs as a local process bound to a UNIX domain socket under your user account. Capture data, accessibility trees, file paths, and annotations never leave your Mac. Stash servers never see capture content.

Do I need to keep Stash running for the MCP server to work?

Yes. The MCP bridge talks to the running Stash app. If Stash is quit, Claude will get a connection error when it tries to call a Stash tool. Stash is designed to run continuously in the menu bar.

Do I need an Apple Developer certificate to install the bridge?

No. The bridge binary ships bundled inside Stash.app at /Applications/Stash.app/Contents/Helpers/stash-mcp, already pre-signed under Stash's Apple team (VJMJQKCRMC) with Hardened Runtime — there's no compile step. Because that team is in Stash's built-in MCP peer-auth allowlist, the bundled bridge is trusted with no extra configuration. If you ever need to admit a different signer, add its team-ID via defaults write ai.gostash.stash mcpExtraTrustedTeamIDs <TEAM>. The mcpAllowUnsignedClients toggle in Settings → Privacy bypasses peer auth entirely, but it lets any unsigned local process connect to the socket — advanced local use only, not a general recommendation.

How do I update the Stash MCP server?

Update Stash itself via Sparkle as normal. The MCP server protocol is stable; tool definitions and trigger phrases are fetched fresh on each Claude connect, so no reinstall is needed when Stash updates.

Is the Stash MCP server free?

Yes. The MCP bridge and Claude skill are included with Stash at no additional cost. Stash itself follows its standard pricing on the pricing page.

Can I use Stash with Claude.ai (web) instead of a desktop client?

No. Claude.ai's web interface does not connect to local MCP servers. Use any of the desktop / CLI clients listed above (Claude Desktop, Claude Code, Cursor, Codex CLI, Continue, Windsurf, Zed, Warp, or Cline).

Related reading