# shelvd-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/NiharRan/shelvd-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1973  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shelvd-mcp

## Description
Shelvd: park ideas from your AI tool. Local, private MCP server.

## Tools
Capabilities this server exposes over MCP:

- **park_idea** — Save an idea with an optional due date (natural language works), project, details and context (repo, branch, files, summary).
- **list_ideas** — Show ideas as a table. Filter by `project`, `status` (`parked`, `due`, `snoozed`, `done`, `all`), `from`/`to` dates and `limit`.
- **get_idea** — Show one idea with its context, notes and history.
- **update_idea** — Edit title, details, project or due date, or append a `note`. Only the fields you give change.
- **search_ideas** — Find ideas by text in title, details, project and notes.
- **start_idea** — Load an idea's details, context and notes as a brief, so the assistant can start work on it.
- **complete_idea** — Mark an idea done.
- **snooze_idea** — Move the due date later, using `until` (date text) or `minutes`.
- **delete_idea** — Permanently delete one idea by id.
- **clear_ideas** — Delete many ideas by scope: `done`, `all` or `project:<name>`. Previews first; only deletes with `confirm=true`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "shelvd-mcp": {
    "command": "npx",
    "args": ["-y","shelvd-mcp"]
  }
}
```

## Documentation

## 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:

```text
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.

_Full upstream README: https://allmcps.com/mcp/shelvd-mcp/readme_