Shelf

Shelf

You build the tools. Shelf keeps them.

A local library for the scripts, dev servers, and one-offs you write for yourself — with remembered launch commands, live status, and logs. Plus a bundled MCP server, so Claude, Cursor, and Codex can query what you've built, launch it, and honestly record what's missing.

Download for macOS · shelfmcp.com · MIT · No account

What it does

• Start a tool from an idea. Describe what you need. Shelf writes a small project that already runs, with your design profile and a build brief, adds it to your library, and opens Claude Code or Codex in the folder to build the rest. Your agent builds; Shelf already knows how to run it.
• One click, no ritual. Point Shelf at a project folder. It scans for scripts, ports, package manager, and DESIGN.md, and suggests a launch config. Accept it and the tool lives in your library.
• Status that doesn't lie. Port-backed tools never report Running until TCP readiness actually succeeds. Live logs, Stop, Restart.
• Agents can see your shelf. A local stdio MCP server exposes your library — list tools, check readiness, launch, stop, read logs.
• Capability gaps, recorded. When nothing in your library matches what an agent was asked to do, Shelf writes it down instead of improvising. Plans, not silent failures.
• Your brand, in every agent. Design profiles hold your colors, type, voice, and logo assets — edited with a live preview, served over MCP. Say "build it with my branding" in any connected agent and it pulls your tokens and a paste-ready brand brief. Seed a profile straight from a project's own CSS variables and Tailwind config — deterministically, nothing guessed — or show an agent a site you love and it saves the extracted brand back as a draft you review.
• Share a tool, or a whole team's worth. Share writes a shelf.json beside your project and copies a shelf://add link; your coworker approves one consent sheet and it's running, with env values never leaving your Mac. A team is a git repo holding a catalog.json: point Shelf at it once and Team Tools lists everything your teammates published, one Install away. No Shelf server, no account — access is whatever your git host already says it is.
• Project memory, checks, and handoffs. Save a project's purpose and decisions, run its typecheck/lint/test/build steps after reviewing them, and hand a failure to your agent with the evidence attached. Agents read all of it; running commands stays in the app.
• Stacks and activity. Start a collection in member order, see what launched and what is waiting on you in Activity, and accept or reject tools an agent asked to register.
• Quick Open (⌘K), menu bar mode, and a shelf:// URL scheme.

Install

Download the signed, notarized DMG:

shelfmcp.com/download

Open it, drag Shelf into Applications, launch from Spotlight. Shelf auto-updates itself from GitHub releases.

Requires macOS on Apple Silicon (M1 or later). No Intel build. No account, no subscription.

Use

1. Click Add tool (or press ⌘N). Starting from scratch? Choose Start a new tool instead.
2. Choose a project folder — Shelf suggests launch command, port, tags, and DESIGN.md when it can.
3. Open the tool and click Launch — or use Quick Open (⌘K) to jump to a tool and ⌘↵ to launch/stop.
4. Watch status and live logs; use Stop / Restart as needed.
5. Open URL, folder, editor (Cursor/VS Code), or Terminal from the detail view.

Menu bar & shelf://

Shelf can sit in the menu bar (Settings → Menu bar). Global show/hide defaults to ⌘⇧Space.

open 'shelf://open'
open 'shelf://quick-open'
open 'shelf://tools/<id>/launch'
open 'shelf://launch?name=Photo%20Prepper'

Action links (launch, stop, restart) require confirmation in Shelf, so a web page or another application cannot control local tools silently.

Project memory and handoffs

Open a tool and choose Memory & handoff to save its purpose, conventions, decisions, known issues, and next steps. Prepare an editable brief with optional environment checks, design direction, and selected run evidence, then review and copy it into your agent. Connected agents can read saved memory through Shelf's MCP interface. See project context for storage, revision conflicts, and the read-only agent contract.

MCP — giving agents your shelf

Easiest path: open Shelf → AI Connections → Connect Claude, Claude Code, Cursor, or Codex. Shelf writes the client MCP config for you (Claude: quit and reopen; Cursor: reload MCP; Codex: restart the client or start a new session), then ask "List my Shelf tools."

Shelf exposes a local stdio MCP server that reads and writes the same library as the GUI, and can launch and stop tools. The packaged app ships a standalone bundle at Shelf.app/Contents/Resources/mcp/.

Manual config (prefer the path shown in MCP Connect inside Shelf):

{
  "mcpServers": {
    "shelf": {
      "command": "node",
      "args": [
        "/Applications/Shelf.app/Contents/Resources/mcp/mcp/server.js"
      ]
    }
  }
}

Capability intelligence is descriptive and local. Agents can discover declared interfaces and record missing capabilities, but Shelf does not connect to or invoke child MCP servers. It exposes your tools, and that's the whole scope.

Example prompts:

"What Shelf tool can batch optimize images?"

"If nothing can fill PDF forms, record that capability gap and explain why."

Project skill for agents: .cursor/skills/shelf-register/SKILL.md.

Where your data lives

Everything Shelf knows is plain JSON in one folder you can read, back up, or delete:

~/Library/Application Support/Shelf/
├── library.json           your tools and collections
├── receipts.json          what launched, when, and who started it
├── logs/                  the last five runs' output per tool
├── capability-gaps.json   what agents needed and couldn't find
├── design-profiles.json   your brands (assets in brand-assets/)
├── project-memory.json    notes you saved for each project
├── verification/          saved checks and their results
├── tool-drafts.json       registrations waiting for you to accept
├── team-catalogs.json     team catalogs you follow
└── prefs.json             your settings

New tools you start in Shelf go in ~/Shelf Tools/ unless you choose another folder.

No account. No cloud sync. No telemetry.

Shelf makes exactly one outbound network request, once per install: a first-launch onboarding survey. The payload is your survey answers (what you shelved first, your role, how you heard about Shelf, which agents you use), an optional name and email you can skip, plus app version and platform. No tool names, no file paths, nothing recurring. The endpoint is site/src/app/api/onboarding/route.ts if you'd rather read it than take our word for it.

MCP responses mask every env value, plus inline KEY=value assignments in launch/stop commands and notes — agents see which keys exist, never the values.

Security notes

• Commands run via /bin/zsh -lc, so your login PATH (nvm/fnm) is available.
• Shelf launches your commands as you. It does not sandbox them. If you shelve something dangerous, Shelf will faithfully run the dangerous thing.
• Interactive prompts and sudo are not supported.

Develop

Requires macOS and Node.js 22.12 or newer.

npm install
npm run electron:dev

Starts the Vite renderer on http://127.0.0.1:5173 and opens the Electron shell.

Local desktop build

npm run install:desktop

Builds Shelf, packages Shelf.app, and copies it to /Applications (when permissions allow) and Desktop. Prefer opening Shelf from /Applications — MCP Connect writes that durable path when both copies exist. Do not launch the raw Electron binary inside node_modules.

First launch of an unsigned local build: right-click → Open if Gatekeeper blocks it. Released DMGs are signed and notarized and do not need this.

MCP server build

npm run mcp:build

Produces a standalone bundle at dist-mcp/mcp/server.js with MCP SDK deps included.

Marketing site

The Next.js site lives in site/. See site/README.md for setup.

CI runs a dependency audit, npm run typecheck, npm run build, npm run smoke:all, and the real-renderer checks (smoke-compact-ui.cjs, smoke-starter-ui.cjs, smoke-renderer-ux.cjs) on macOS for pushes and PRs to main. Release tags run the same gate before signing.

Status

See the latest release and changelog for the shipped version. Issues and feedback are welcome.

License

MIT — see LICENSE.