Log inSubmit server
Shelvd MCP logo

Shelvd MCP

Local MCP backlog for parking, searching, scheduling, and completing ideas stored in a private JSON file.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Shelvd MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "shelvd-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "shelvd-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command started, but didn't respond the way we expected when we tried to talk to it.

npx -y shelvd-mcp

initialize succeeded but no response to tools/list.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked .

Overview

shelvd-mcp is a local, private MCP server that gives AI clients an idea backlog backed by a JSON file on the user's machine. Its tools save ideas with project, due-date, and development-context fields, then list, search, update, snooze, start, complete, or delete them. Use it when ideas arise during coding and need to be preserved for later work without sending them to a hosted service. It runs as a standard stdio server and can also expose due-idea reminders at session start.

Use cases

  • Park feature ideas while coding
  • Search a project-specific backlog
  • Resume an idea with its repository context
  • Snooze work until a later date
  • Review due ideas at session start

Key features

  • Local JSON-backed idea storage
  • Natural-language due dates
  • Project and status filtering
  • Repository, branch, and file context
  • Idea notes and work briefs
  • Due-idea session reminders

Tools10

What Shelvd MCP lets your agent do. Expand a tool for its parameters.

Self-reported~220 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8h ago via OSV.dev · shelvd-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads1kPackage downloads in the last 30 days.
Last commit9d agoMost recent push to the default branch.
Install checkInconclusiveStarted but did not complete the MCP handshake in our test.
Tools exposed10Callable tools this server registers over MCP.

How Shelvd MCP works

What shelvd-mcp does

shelvd-mcp provides an idea-parking and lightweight backlog workflow inside an MCP-compatible AI client. Ideas can include a title, details, project, optional due date, and context such as the repository, branch, files, or a summary. The stored record also supports notes and history, giving an assistant enough information to resume an item later.

Data remains local in a JSON file rather than being sent to a remote service. By default, the file is located at ~/.shelvd/ideas.json; the containing directory uses mode 0700 and the file uses mode 0600. The storage location can be changed with SHELVD_DIR.

How it works

Run the package as an MCP server over stdio. Claude Code can register it with:

Terminal
claude mcp add shelvd -- npx -y shelvd-mcp

Other MCP clients can launch npx -y shelvd-mcp as their stdio server command. Once connected, an assistant can park an idea such as a feature request, retrieve the backlog, and resume an item through the start_idea brief.

At the beginning of a session, the server mentions ideas that are due or overdue in its first response. A separate hook command, npx -y shelvd-mcp hook, prints a configuration snippet for a Claude Code SessionStart hook. The command does not modify ~/.claude/settings.json; the printed snippet must be added manually.

Tools and capabilities

  • park_idea creates an item with optional natural-language due dates, project information, details, and coding context.
  • list_ideas presents ideas in a table and accepts project, status, date-range, and limit filters. Status values include parked, due, snoozed, done, and all.
  • get_idea retrieves an item's context, notes, and history.
  • update_idea changes only the fields supplied, including title, details, project, due date, or an appended note.
  • search_ideas searches titles, details, projects, and notes.
  • start_idea turns an item's details, context, and notes into a work brief.
  • complete_idea marks an item done, while snooze_idea moves its due date using a date expression or a number of minutes.
  • delete_idea removes one item permanently. clear_ideas previews bulk deletion by done status, all items, or project, and requires confirm=true to perform it.

Limitations and notes

Concurrent writes from two clients in the same millisecond can lose one write because the file is not protected by a file lock. If the JSON file is corrupt, shelvd-mcp leaves it unchanged and reports the error; repair or move the file before retrying.

Phone reminders using nagEveryMinutes require the hosted Pro version. The local server is intended for local storage and session-based access through an MCP client.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Shelvd MCP

shelvd-mcp is an MCP server that connects AI clients to a local JSON idea backlog. Its main tools park, list, search, retrieve, update, start, complete, snooze, and delete ideas, with support for due dates, projects, notes, and coding context such as repositories, branches, and files.

Install it by running `npx -y shelvd-mcp` as a stdio server in your MCP client. For Claude Code, use `claude mcp add shelvd -- npx -y shelvd-mcp`; other MCP clients can launch the same npx command.

shelvd-mcp stores ideas in `~/.shelvd/ideas.json` by default. Set `SHELVD_DIR` to use another directory. The default directory is restricted to the user and the data file is created with restrictive permissions.

Yes, shelvd-mcp works with Cursor as an MCP client through its stdio server command. Run `npx -y shelvd-mcp` from the client configuration, then use the idea-management tools through Cursor.

Related MCP servers

All in Developer Tools All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewShelvd MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/shelvd-mcp?style=directory)](https://allmcps.com/mcp/shelvd-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/shelvd-mcp"><img src="https://allmcps.com/api/badge/shelvd-mcp?style=directory" alt="Shelvd MCP on AllMCPs" /></a>