Vibe Board VE
This MCP server provides persistent, cross-session memory for AI agents (like Claude Code) via a Firestore-backed board, enabling task tracking, project management, session handoffs, activity logging, and team-shared memory.
Project Management: Create, list, update projects (active/paused/completed/archived) with priority and metadata.
Task Management: Create, fetch, update, bulk-update, and delete tasks with statuses (backlog→todo→in_progress→review→done/blocked), priorities, assignments, dependencies, subtasks, and RIPER mode.
Session Lifecycle: Start sessions (auto-abandons stale ones), end sessions with handoff notes, and read handoff context mid-session.
Activity Audit Log: Log free-form activities (comments, decisions, blockers) and query them filtered by task, session, agent, or action.
Handoff Continuity: Start a new session and automatically receive the previous session's progress summary, handoff notes, and active tasks.
Batch Operations: Update up to 100 tasks in one call, move tasks across projects, or change status/priority/assignment in bulk.
Safety Guards: Task deletion is blocked for non-done tasks unless overridden; bulk updates are all-or-nothing; activity deletion is bounded.
Shared Memory: Save, search, and delete team-wide shared memories so agents can pass knowledge between sessions.
Gate Events (advanced): Query and ingest gate events for review-gate workflows, with hardened ingest and quarantine handling.
Supports optional Docker worker deployment as part of the Vibe Coding Framework bundle, providing containerized execution environment for the MCP server.
Provides Firestore-backed persistent memory storage for AI agents, enabling tasks, progress, decisions, and handoff notes to survive across sessions through Firestore database integration.
Vibe Board MCP (ve-vibe-board)
Your agent, but it remembers. Firestore-backed MCP server that gives Claude Code (and any MCP-speaking agent) persistent memory across sessions — tasks, progress, decisions, and handoff notes that survive context compaction and session death.
Companion repo: HuntsDesk/ve-kit — Vibe Coding Framework & Persistent Memory for Claude Code. ve-kit bundles this MCP server, a RIPER-CAT workflow, review-gate hooks, and an optional Docker worker.
Part of Vibe Entrepreneurs — a community for any vibe coders shipping real work with AI. Come say hi: vibeentrepreneurs.com.
Why this exists
Sound familiar?
You're six tool calls into a refactor. Context compacts. The agent comes back with vibes but no plan.
You start a new session tomorrow. It re-reads the same files, re-asks the same questions, re-decides things you already decided.
You watched it write a perfect TodoWrite checklist — then the conversation ended, and the checklist evaporated with it.
You opened three agents in parallel. None of them know what the others did.
This is what statelessness feels like in practice. The agent is brilliant for an hour and amnesiac forever after.
Vibe Board is where the state goes instead. It's a shared task + session board that lives outside any single conversation — in Firestore, not in context.
Agents create tasks during planning — they survive the session
Progress gets tracked during execution — visible to the next run
Handoff notes get written when sessions end — with references to the exact tasks still open
The next session calls
board_create_session, reads the handoff, and resumes where the last one stopped
What you get: an agent that shows up on Tuesday knowing what it was doing on Monday. No re-explaining. No lost plans. No TodoWrite graveyard.
Free to run on Firebase's free tier.
Related MCP server: Google Workspace MCP VE
21 MCP tools
Category | Tools |
Projects |
|
Tasks |
|
Sessions |
|
Activity |
|
Gate events (2.2.0; 2.2.1 hardens ingest: bad rows quarantined whole, handled-prefix watermark, poison brake, |
|
Shared memory |
|
Twenty-one tools, one job: give the agent a place to put state that isn't the conversation. tools/list against your own build is the authority if this table ever drifts.
Install
1. Clone + build
git clone https://github.com/HuntsDesk/ve-vibe-board.git
cd ve-vibe-board
npm install
npm run build2. Set up Firebase
Create a Firebase project (free tier works). Enable Firestore in Native mode. Create a service account with roles/datastore.user and download the key JSON.
GOOGLE_APPLICATION_CREDENTIALS accepts either a file path to the key JSON (canonical) or the raw JSON contents inline (handy for sandboxed environments like Glama's browser MCP Inspector, CI secrets, or Cloud Run's inlined-secret pattern).
Also deploy the Firestore composite indexes. The repo ships with firestore.indexes.json declaring all 5 required indexes (sessions, tasks, projects, activity_log). Deploy them with one command:
# From the ve-vibe-board repo root (contains firebase.json + firestore.indexes.json)
firebase use YOUR_PROJECT_ID
firebase deploy --only firestore:indexesgate_events (added 2026-09-16, 7 indexes): dev+ts↓, hook+ts↓, event+ts↓, hook+event+ts↓, dev+hook+ts↓, path+ts↓, paths(array-contains)+ts↓ — every filter combination board_query_gate_events issues. Missing one surfaces as FAILED_PRECONDITION; the tool returns error: missing_composite_index with the console link instead of throwing.
Requires the Firebase CLI (npm install -g firebase-tools) authenticated with an account that has roles/datastore.indexAdmin on the project. Wait 1-5 min for indexes to build.
gcloud firestore indexes composite create \
--project=YOUR_PROJECT_ID \
--collection-group=sessions \
--field-config field-path=project_id,order=ascending \
--field-config field-path=status,order=ascending \
--field-config field-path=ended_at,order=descending
gcloud firestore indexes composite create \
--project=YOUR_PROJECT_ID \
--collection-group=tasks \
--field-config field-path=project_id,order=ascending \
--field-config field-path=status,order=ascending
gcloud firestore indexes composite create \
--project=YOUR_PROJECT_ID \
--collection-group=tasks \
--field-config field-path=project_id,order=ascending \
--field-config field-path=assigned_agent,order=ascending \
--field-config field-path=status,order=ascending
gcloud firestore indexes composite create \
--project=YOUR_PROJECT_ID \
--collection-group=projects \
--field-config field-path=status,order=ascending \
--field-config field-path=updated_at,order=descending
gcloud firestore indexes composite create \
--project=YOUR_PROJECT_ID \
--collection-group=activity_log \
--field-config field-path=task_id,order=ascending \
--field-config field-path=created_at,order=descending3. Configure Claude Code
Add to your project's .mcp.json:
{
"mcpServers": {
"vibe-board": {
"command": "node",
"args": ["/absolute/path/to/ve-vibe-board/dist/index.js"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/your-key.json"
}
}
}
}Allow the tools in .claude/settings.local.json:
{
"permissions": {
"allow": [
"mcp__vibe-board__board_get_projects",
"mcp__vibe-board__board_create_project",
"mcp__vibe-board__board_update_project",
"mcp__vibe-board__board_get_tasks",
"mcp__vibe-board__board_get_task",
"mcp__vibe-board__board_create_task",
"mcp__vibe-board__board_update_task",
"mcp__vibe-board__board_bulk_update_tasks",
"mcp__vibe-board__board_delete_task",
"mcp__vibe-board__board_create_session",
"mcp__vibe-board__board_end_session",
"mcp__vibe-board__board_get_handoff",
"mcp__vibe-board__board_log_activity",
"mcp__vibe-board__board_get_activity"
]
},
"enabledMcpjsonServers": ["vibe-board"]
}4. Verify
Start a new Claude Code session and call board_get_projects. Empty array = success.
Agent rules (paste into CLAUDE.md)
Drop this into your project's CLAUDE.md (or equivalent agent-instructions file). It's the same protocol the ve-kit framework ships, condensed for standalone MCP installs. The MCP server gives the agent a place to put state — these rules teach it to actually use it.
## Vibe Board
Persistent task tracking across sessions via Firebase Firestore MCP tools (`board_*`).
**Mandatory for every substantive session** (any session where you read, write, plan, debug, or deploy code).
### Use Board Tasks, NOT TodoWrite
TodoWrite is ephemeral — it dies when the session ends. Board tasks persist forever and enable cross-session handoff. When you would reach for TodoWrite to track multi-step work, use `board_create_task` instead.
**Nothing exists unless it's on the board.** If an action item, future phase, recommendation, or follow-up is mentioned in conversation or discovered in a document but has no board task, it WILL be forgotten. The board is the single source of truth for "what needs to be done." Conversation text, plan docs, and strategy docs are reference material — the board is the task list. When in doubt, create the task. A redundant board task costs nothing; a forgotten action item costs real work.
### Proactive Triggers
These are condition → action pairs. When the condition is true, take the action immediately.
| Condition | Action |
|-----------|--------|
| Session starts (substantive work) | `board_create_session` before any other work |
| Context compacted / continuation session | `board_create_session` IMMEDIATELY — compaction loses the active session ID |
| Multi-step task (3+ steps) | `board_create_task` for each step |
| Batch of items (fix 5 bugs, review 3 files) | Parent task + subtask per item via `board_create_task` |
| New work discovered during execution | `board_create_task` immediately |
| Significant decision or blocker | `board_log_activity` |
| Start working on a task | `board_update_task` → `in_progress` + set `assigned_agent` to your name |
| Finish a task | `board_update_task` → `done` |
| Review/audit produces findings | Parent task per severity tier + subtask per finding |
| Deploying a new service for the first time | `board_create_task` for: verify deployment, create CI/CD trigger, push to prod |
| Committing + pushing code | `board_log_activity` with commit hash; update related tasks |
| Read a doc/plan with unbuilt phases or pending items | `board_create_task` for each actionable item not already on the board |
| Mention a future action item in conversation | `board_create_task` immediately — conversation text is ephemeral, board tasks are permanent |
| A sub-agent reports a finding or recommendation | `board_create_task` if it requires future work (don't let it exist only in conversation) |
| User says "handoff" or signals session end | Create board tasks for ALL pending next steps, THEN `board_end_session` |
| Session ending OR context getting long | `board_end_session` with handoff notes |
**The test**: If this session died right now, could the next session reconstruct what you were doing from the board alone? If not, you haven't been proactive enough.
**The second test**: If a documented plan has unchecked items, unbuilt phases, or "pending" status markers — and there's no corresponding board task — that's a gap. Every actionable item in every plan doc should have a board task. Plans without board tasks get forgotten.
### Session Lifecycle
**Starting a session** (before any other work — **including after context compaction**):
**Context compaction destroys the active session ID.** If you're continuing from a compacted conversation, you MUST call `board_create_session` before doing anything else. This is the #1 failure mode — compaction preserves your behavioral patterns but loses board state.
1. Call `board_get_projects` to see all active projects
2. **Match work to the correct project** — read project names/descriptions and pick the best fit. Do NOT default to one project for everything. Use a general catch-all project only when no specific project fits.
3. Call `board_create_session` with the matched `project_id`
- This auto-abandons any stale sessions and returns handoff context
- Read the handoff carefully — it contains what the last session accomplished and what's next
4. Review active tasks via the handoff response or `board_get_tasks`
**During a session:**
- **Planning**: Create all tasks on the board immediately with status `todo`. This ensures the plan survives even if the session crashes before execution.
- **Reviewing**: Review the *task list on the board*, not just prose. Call `board_get_tasks`, then use `board_log_activity` with `task_id` and `action: "commented"` to attach review comments to specific tasks. ALL review output MUST go through the board — conversation text disappears when sessions end.
- **Review findings → board tasks**: When a review produces findings, every finding must become a board task — not just an activity log comment. Create one parent task per severity tier (e.g., "Tier 1: BLOCKING items"), then subtasks for each finding using `parent_task_id`. Map priorities: BLOCKING/FAIL → `critical`, HIGH/WARN → `high`, LOW/INFO → `low`. Include enough context in each subtask's description to fix the issue without re-reading the review.
- **Executing**: Move tasks to `in_progress` as work begins, then `done` when complete. `started_at` is set automatically on first move to `in_progress` — work duration = `completed_at - started_at`.
- **Committing**: Log the commit hash via `board_log_activity` on related tasks. When deploying a new service for the first time, create follow-up tasks: (1) verify deployment, (2) create CI/CD trigger, (3) push to production. These are predictable follow-ups — don't wait for the user to ask.
- **Tracking your own work**: The board isn't just for project plans — it tracks what YOU are doing right now. When you receive a batch of items, create a **parent task** for the batch and **subtasks** for each item using `parent_task_id`. Move each subtask to `in_progress` → `done` as you work. This creates a recoverable checkpoint: if the session dies mid-batch, the next agent sees exactly which items are done and which remain.
- **Sub-agent delegation**: When spawning specialist sub-agents that produce detailed findings, instruct them to write results directly to the board. Include the `project_id` and parent task ID in the prompt. The sub-agent returns only a brief summary. This keeps the main agent's context lean while preserving full detail on the board. Pattern: `"Write all findings to the Vibe Board (project: PROJECT_ID, parent task: TASK_ID). Return only a 1-sentence summary to me."`
- **All modes**: Log notable events via `board_log_activity`. Create additional tasks as new work is discovered — the board should always reflect the current state of work.
**Ending a session** (before the session ends or when the user signals they're done):
1. **Scan your tasks**: Check for any tasks still `in_progress` that you own — mark them `done` if complete, or add a `board_log_activity` comment explaining what remains.
2. **Create tasks for all next steps**: Every pending follow-up must exist as a board task BEFORE ending. Do not list future work only in handoff prose — if it's worth mentioning as a next step, it's worth tracking as a task.
3. Call `board_end_session` with progress_summary, handoff_notes (referencing task IDs, not just prose), and context_artifacts.
**This is the most critical step.** A session without handoff notes is a session whose context is lost forever.
**Proactive ending**: If you sense the conversation is getting long or you are approaching context limits, call `board_end_session` immediately — even a partial handoff is infinitely better than an abandoned session with no notes.
### Task Status Flow
backlog → todo → in_progress → review → done
↓
blocked
### Priority Levels
- **critical**: Blocking other work, needs immediate attention
- **high**: Important, should be next
- **medium**: Standard priority (default)
- **low**: Nice to have, do when time allowsWant more?
The above is the standalone protocol. If you also want the broader framework — RIPER-CAT operational modes, a processor agent for delegated multi-specialist work, review-gate hooks, an autonomous Docker worker — see HuntsDesk/ve-kit → docs/ve-kit/02-VIBE-BOARD.md for the canonical reference and the rest of the kit.
License
MIT. See LICENSE.
Related
HuntsDesk/ve-kit— full Vibe Coding Framework that bundles this MCP serverHuntsDesk/ve-gws— VE Google Workspace MCP (sibling in the ve-* family)
Available Tools
14 toolsboard_bulk_update_tasksA
Apply the same update to multiple tasks in one call. Useful for consolidation (move N tasks to a different project) or bulk status/priority/agent changes. All tasks are validated first — if any task is missing, NO tasks are updated (all-or-nothing). Activity log entries are written per task.
Inputs: task_ids (required), project_id, status, priority, +1 more.
board_create_projectA
Create a new project to group tasks and sessions under a shared goal. Projects are the top-level container — every task and session must belong to one. Use sparingly: create a new project for major initiatives (3+ related tasks), not for every piece of work. New projects are created with status='active' and priority='medium' (unless overridden). Returns { id, name, status, priority, message }.
Inputs: name (required), description, priority, metadata.
board_create_sessionA
Start a new work session on a project and get the previous session's handoff. Side effect: any currently-active sessions on the same project are automatically marked 'abandoned' with ended_at=now — there's only ever one active session per project. Call this at the start of every substantive session so the next one can pick up where you left off. The returned handoff includes: last_session (progress_summary + handoff_notes + context_artifacts from the previous run), active_tasks (priority-sorted non-done tasks), and recent_activity (last 20 activity_log entries). Returns { session_id, abandoned_sessions, handoff, message }.
Inputs: project_id (required), session_type, metadata.
board_create_taskA
Create a task in a project. Status defaults to 'todo' and priority to 'medium' if not specified. If the initial status is 'in_progress', started_at is auto-set to now; if 'done', completed_at is auto-set. Writes an activity_log entry for audit. Use parent_task_id to create a subtask under another task (common pattern for decomposing work). Use depends_on to express ordering ('task B blocks on task A'). Returns { id, title, status, priority, message }.
Inputs: project_id (required), title (required), description, status, +6 more.
board_delete_taskA
Hard-delete a task and optionally its subtasks. Safety guard: by default only allows deleting tasks with status=done (prevents deleting in-progress work). Pass require_done=false to override. Also deletes associated activity_log entries. This is irreversible — cannot be undone.
Inputs: task_id (required), require_done, cascade_subtasks.
board_end_sessionA
End the current session with a progress summary and handoff notes. This is the single most important call for cross-session continuity — without it, everything you did this session is invisible to the next one. Marks the session status='completed' and sets ended_at=now. The next board_create_session will surface this session's progress_summary, handoff_notes, and context_artifacts in its handoff response. Reference specific task IDs in handoff_notes (the next session reads this as prose, not a parsed list). Returns { session_id, status, message }.
Inputs: session_id (required), progress_summary (required), handoff_notes, context_artifacts.
board_get_activityA
Query the activity_log. Filter by task_id, session_id, agent_name, or action. Results are ordered newest-first and capped at limit (default 50, max 200). Useful for auditing what happened on a task, reconstructing a session, or following an agent's actions.
Inputs: task_id, session_id, agent_name, action, +1 more.
board_get_handoffA
Read the full handoff context for a project without starting a new session. board_create_session already returns this automatically at session start — use board_get_handoff mid-session when you need to re-check what was pending, or when a background agent needs context without claiming the session slot. Returns: project (id/name/status/description), last_session (progress_summary + handoff_notes + context_artifacts from the most recent completed/abandoned session, or null if none), active_tasks (all non-done tasks sorted critical → low priority, with id/title/status/priority/assigned_agent/riper_mode/depends_on), active_task_count, and recent_activity (last 20 activity_log entries, newest-first).
Inputs: project_id (required).
board_get_projectsA
List all projects with per-status task counts. Call this at session start to discover available projects before creating tasks or sessions — the returned IDs are required inputs to board_create_session, board_create_task, and most other tools. Results are sorted by priority descending (critical → low), then updated_at descending as tiebreaker. Projects without an explicit priority are treated as 'medium' for sort purposes (backward compat). Each entry includes: id, name, description, status, priority, metadata, ISO-formatted created_at/updated_at, task_counts (e.g., {todo: 3, in_progress: 1, done: 12}), and total_tasks. Use this over board_get_tasks when you don't yet know which project to target.
Inputs: status.
board_get_taskA
Fetch a single task by its ID. Use this when you have a task ID (from board_create_task, a handoff note, or an activity_log entry) and need the full task record — for listing many tasks under a project, use board_get_tasks instead. Returns every field: id, project_id, title, description, status, priority, assigned_agent, parent_task_id, depends_on, riper_mode, metadata, and ISO timestamps (created_at, updated_at, started_at, completed_at). Returns { error } when the task doesn't exist rather than throwing — callers should check for the error key before treating the result as a task.
Inputs: task_id (required).
board_get_tasksA
List tasks in a project with optional filters. Results are sorted client-side by priority (critical → low) — not by creation time. By default excludes done tasks (pass include_done=true or set status='done' to see them). Use this for mid-session checks: almost always pass a status filter (e.g., 'in_progress' or 'todo') to keep responses tight. For a single task by ID, use board_get_task instead. Returns an array of task objects with id, project_id, title, description, status, priority, assigned_agent, parent_task_id, depends_on, riper_mode, metadata, and ISO timestamps (created_at, updated_at, started_at, completed_at).
Inputs: project_id (required), status, priority, assigned_agent, +1 more.
board_log_activityA
Append an entry to the activity_log — a write-only audit stream of what agents did, decided, or observed. Use this for: RESEARCH observations the next session should see, decisions made during PLAN/REVIEW, blockers, notable failures, or any context that shouldn't be lost. Most status/assignment changes via board_update_task and board_create_task already write their own activity_log entries automatically — call this explicitly for free-form comments (action='commented') or arbitrary actions. Read back via board_get_activity. Returns { id, action, message }.
Inputs: agent_name (required), action (required), details, task_id, +2 more.
board_update_projectA
Update a project's status (active/paused/completed/archived), priority, name, description, or metadata. Use this to pause projects that are on hold, archive completed projects so they don't clutter the active list, or re-rank portfolio priority during weekly reviews. Pass null to description/metadata to clear them.
Inputs: project_id (required), status, priority, name, +2 more.
board_update_taskA
Update a task's status, assignment, priority, RIPER mode, project, or other fields. Pass project_id to move the task to a different project (the target project must exist; subtasks are NOT auto-moved — caller must move them separately if needed).
Inputs: task_id (required), status, priority, assigned_agent, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a unique resource/action combination—project, session, task, activity, and handoff—with no overlap. Singular vs plural 'get' tools clearly separate single-fetch from list-fetch.
All tools follow the 'board_verb_noun' snake_case pattern consistently. Verbs like create, get, update, delete, end, log, bulk_update are uniformly applied, and noun forms (singular/plural) match their function.
14 tools is well-scoped for a board management server covering tasks, projects, sessions, and activity logging. The count feels neither bloated nor sparse—each tool serves a clear, necessary purpose.
Core CRUD operations are present for tasks and projects, plus session lifecycle and activity tracking. Minor gaps exist: no project deletion (only status update), no single-project fetch by ID, and no session list endpoint. These are non-critical for typical workflows.
Maintenance
Related MCP Connectors
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Notes, tasks, habits, journal and 6 more tools Claude can read and change, with undo. Free.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Related MCP Servers
- AlicenseAqualityDmaintenancePersistent, cross-session task management for Claude Code. 24 MCP tools for tasks, projects, dependencies, and docs. 7 skills for planning, standups, and handoffs. Event-sourced storage with per-project isolation.5MIT
- AlicenseAqualityDmaintenanceMost Google Workspace MCPs let you read. This one lets you write — 28 authoring tools on top of taylorwilsdon/google_workspace_mcp, including markdown-to-Docs, smart chips, and recursive Drive copy.1002MIT
- AlicenseAqualityCmaintenancePersistent knowledge base tools for Claude Code that store project context, decisions, and patterns locally across sessions, eliminating cold starts.8MIT
- AlicenseAqualityBmaintenancePersistent, shared memory for Claude across sessions and clients (Code, Desktop, Cowork) — deterministic diff reads, checkpoints, cross-client task handoff, and project-wide search. 100% local and deterministic, no API keys, no LLM summarization.64MIT