recap-mcp
Recap
Your AI project manager. Plain markdown. Local-first. Open source.
Recap is an MCP server that gives Claude persistent memory of your ongoing projects. Job searches, side projects, learning goals, writing efforts, anything you work on over weeks or months. Your data lives as plain markdown files in a folder you own.
Why Recap
Claude forgets between conversations. You spend the first five minutes of every chat re-explaining what you're working on, what you decided last time, and what's pending. Recap fixes that.
Local-first: your workspace is a folder of markdown files. Nothing leaves your machine.
Plain markdown: open it in VS Code, Obsidian, vim, anything.
Open source: MIT licensed, no vendor lock-in.
Project-shaped, not blob-shaped: structured around projects, tasks, sessions, and notes, not opaque memory dumps.
Eleven focused tools: no kitchen sink, no bloat.
Related MCP server: Cortex
Install
Requires Node.js 18+.
npx recap-mcp initThat single command:
Creates a workspace folder at
~/recap-workspace/Adds Recap to your Claude Desktop config
Backs up any existing Claude config to
.bak
Then quit Claude Desktop, reopen it, and say "hi". Recap will guide you through your first project.
The eleven tools
Tool | Purpose |
| Run at session start. Loads workspace status, active projects, recent activity. |
| List projects, filter by status. |
| Start a new project, optionally seeded from a template. |
| Load full context for one project (description, open tasks, recent sessions). |
| Add a task with optional priority, due date, notes. |
| List tasks for a project, filterable by status. |
| Change status, priority, due date, notes, or title. |
| Remove a task. |
| Save a structured session entry: worked on, decisions, next steps. |
| Drop a timestamped note into a project. |
| Fuzzy ranked search across the entire workspace. |
Templates
Recap ships with six starter templates:
generic(clean slate)job-searchside-projectlearningwritingmoving
Pass --template to project_create (or have Claude do it) to seed a project with starter tasks and a knowledge file.
Workspace structure
~/recap-workspace/
├── .recap/
│ └── config.json
├── projects/
│ └── job-search-2026/
│ ├── project.md
│ ├── tasks.md
│ ├── notes.md
│ ├── sessions/
│ │ └── 2026-05-20.md
│ └── knowledge/
│ └── starter.md
└── archived/Plain markdown with YAML frontmatter. You can cd into it and git init if you want version control. Open it in Obsidian if you want a nice viewer.
Configuration
The workspace path defaults to ~/recap-workspace/. Override it with:
export RECAP_WORKSPACE_PATH=/path/to/your/workspaceOr pass --workspace to recap-mcp init.
Other settings live in .recap/config.json:
{
"version": "0.1.0",
"briefing": { "recent_days": 14, "max_active_projects": 5 },
"search": { "max_results": 10 }
}Troubleshooting
Run npx recap-mcp doctor for diagnostics.
If Claude Desktop doesn't see Recap after install:
Make sure you fully quit Claude Desktop (not just closed the window).
Check
~/recap-workspace/exists.Check your Claude Desktop config has
mcpServers.recapentry.
Privacy
Recap runs entirely on your machine. There is no telemetry, no analytics, no remote calls. Your projects, tasks, notes, and session logs never leave your computer.
License
MIT. See LICENSE.
Status
v0.1.0. Early. Feedback and issues welcome at https://github.com/shivam-singh-git/recap-mcp/issues.
Available Tools
11 toolsbriefingA
Session-start orientation. Run this at the beginning of every conversation to load workspace status, active projects, recent activity, and stale projects. Returns a 'welcome_flow_active' flag if the workspace is empty.
Inputs: no named parameters.
project_briefA
Load full context for a single project: description, body, open tasks, blocked tasks, knowledge files, and recent session logs. Use this when you need to dive deep into one project.
Inputs: project (required), recent_sessions.
project_createA
Create a new project. Optionally seed it from a template: 'generic', 'job-search', 'side-project', 'learning', 'writing', or 'moving'. Each template adds starter tasks and an optional knowledge starter file.
Inputs: name (required), template, description.
project_listA
List projects in the workspace. Filter by status (active, archived, all). Returns slug, name, description, task counts, and last-touched dates.
Inputs: status.
quick_noteA
Drop a timestamped note into a project. For stray thoughts that don't fit a session log.
Inputs: content (required), project (required).
searchA
Fuzzy ranked search across projects, tasks, sessions, and notes. Ranks by recency, type relevance, and field match. Use to recall anything in the workspace.
Inputs: query (required), type, project, max_results.
session_logA
Log a session entry for a project: what was worked on, decisions made, next steps. The core 'log progress' tool. Run at the end of a working session.
Inputs: project (required), worked_on (required), date, decisions, +2 more.
task_addB
Add a task to a project. Supports priority, due date, and notes.
Inputs: title (required), project (required), due, notes, +1 more.
task_deleteB
Delete a task from a project.
Inputs: project (required), task_id (required).
task_listA
List tasks for a project. Filter by status (open, done, blocked, all). Sorted by priority then due date.
Inputs: project (required), status.
task_updateC
Update a task. Change status, priority, due date, notes, or title. Pass null for due/notes to clear them.
Inputs: project (required), task_id (required), due, notes, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource and action: project, task, session, note, or search. Even session_log and quick_note are clearly separated by structured end-of-session entries vs. stray timestamped thoughts, so an agent should rarely mis-select.
Most tools follow a readable resource_action pattern: project_list, project_create, task_add, task_update, task_delete. A few outliers like briefing, quick_note, and search break that pattern, but the naming remains largely predictable and unambiguous.
Eleven tools is a well-scoped size for a workspace/project/task/session management domain. Each tool covers a meaningful operation without unnecessary overlap or bloat.
Task CRUD is complete, and search/project_brief provide solid retrieval. However, project lifecycle management is incomplete: projects can be created and listed but not updated, archived, or deleted, which is notable given archived and stale project statuses are referenced.
Maintenance
Related MCP Connectors
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives Claude Code cross-session memory persisted to a plain .claude-memory.md file in your repo.MIT
- AlicenseNot gradedqualityDmaintenancePersistent memory MCP server for Claude Code that captures and recalls project context across sessions, eliminating the need to re-explain architecture and decisions daily.135 npm1MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for project planning inside Claude. It tracks progress, knows your codebase, and resumes exactly where you left off every session.9 npm5-
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server giving Claude persistent memory via entities, observations, history, and reminders, backed by a lightweight Node/SQLite backend.17 npm1MIT