@vibemap.ai/mcp-server
Connects an IDE agent to VibeMap to load full project specs into context, and to push a local codebase back into VibeMap as structured specs and workflow state.
Projects: list/create projects, fetch full project context (features, stories, personas, pages, DB schema, all toggleable), and pull a code-shaped atomic blueprint.
Spec authoring: list/create/update features, user stories, and BDD acceptance criteria; read table- and page-level access rules; export a page's generated source code.
Kanban / agentic lifecycle: view the live board, get the next ready criterion, claim criteria, report progress, submit for review (with git SHA + diff URL), resolve reviews (CI token or signed-in user only), block/unblock, and stream transition events;
vibemap_update_kanban_statusis deprecated.Version control: list changesets (every write is wrapped in one), optionally with per-op diffs.
Codebase: scan a local directory, reverse-engineer it into features (server-side AI, polled by sessionId), submit/fetch a structural code map, report changed files to flag spec drift, and poll generation status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@vibemap.ai/mcp-server load project specs for my app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@vibemap.ai/mcp-server
Connect your IDE agent to VibeMap via the Model Context Protocol. Load project specs into any MCP-compatible AI coding agent, or reverse-engineer an existing codebase back into structured VibeMap assets.
Quick Start
{
"mcpServers": {
"vibemap": {
"command": "npx",
"args": ["-y", "@vibemap.ai/mcp-server"],
"env": {
"VIBEMAP_API_KEY": "vm_your_token_here",
"VIBEMAP_BASE_URL": "https://vibemap.ai"
}
}
}
}Generate your API key at vibemap.ai → Account → Developer → API Keys.
Related MCP server: CodeLocal
What It Does
Outbound (VibeMap → IDE): Load your full project context — features, user stories, acceptance criteria, personas, pages, and DB schema — into your IDE agent. The agent builds to spec and updates your VibeMap kanban in real time as it works.
Inbound (IDE → VibeMap): Point the server at an existing codebase and VibeMap's AI will reverse-engineer it into a structured set of features, user stories, and acceptance criteria.
Requirements
Node.js ≥ 18
A VibeMap account
IDE Setup
Claude Desktop
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"vibemap": {
"command": "npx",
"args": ["-y", "@vibemap.ai/mcp-server"],
"env": {
"VIBEMAP_API_KEY": "vm_your_token_here",
"VIBEMAP_BASE_URL": "https://vibemap.ai"
}
}
}
}Fully restart Claude Desktop after saving. Confirm the 🔨 hammer icon appears in the message box.
Cursor
Open Settings → MCP and add:
{
"vibemap": {
"command": "npx",
"args": ["-y", "@vibemap.ai/mcp-server"],
"env": {
"VIBEMAP_API_KEY": "vm_your_token_here",
"VIBEMAP_BASE_URL": "https://vibemap.ai"
}
}
}Windsurf
Same format as Cursor. Add to your Windsurf MCP settings file and restart.
Environment Variables
Variable | Description | Default |
| Your Personal Access Token ( | Required |
| VibeMap instance URL |
|
Tools
The server exposes 55 tools via the vibemap_ prefix.
Projects & context
Tool | Description |
| List all your projects |
| Create a new project (use before |
| Load full project specs into agent context |
| Get the code-shaped blueprint of the whole project (large; for scaffolds and audits, not for building a single ticket: use |
| List table- and page-level access rules (with |
| Retrieve a page and its section source code |
Personas & pages (spec authoring)
Tool | Description |
| Create a rich user persona (demographics, goals, pain points, …) |
| Create a page/screen in the project's page inventory |
| Persist the database schema (tables → columns → relationships) in one call |
Conversational agent (hosted, metered)
Tool | Description |
| Drive VibeMap's full conversational agent for one turn (same brain as the in-app chat). Metered — uses VibeMap tokens. Destructive turns return a plan + |
Features
Tool | Description |
| List features with filtering |
| Create a new feature |
| Update feature fields or status (validates transitions). For spec authoring only: while building, use |
User stories
Tool | Description |
| List stories by project or feature |
| Create a user story |
| Update story fields or status (validates transitions). For spec authoring only: while building, use |
Acceptance criteria
Tool | Description |
| Fetch BDD criteria |
| Create a BDD acceptance criterion |
| Update a criterion's content (Given/When/Then, description). Status is not writable here: use the lifecycle tools below. For spec authoring only: while building, use |
Kanban — board & agentic lifecycle
Tool | Description |
| Get a real-time board view |
| The build order: criteria grouped by sprint in dependency order, with state |
| Get the next criterion to work on, its story bundle, and a |
| Claim every claimable criterion of a story at once; returns a context pack for each |
| Claim a criterion ( |
| Everything needed to build one criterion in a few thousand tokens (use instead of the whole blueprint) |
| Heartbeat with the current |
| Submit a criterion for review with the changed files and the named tests that prove it (→ |
| Submission history of a criterion: files, tests and verdict per attempt |
| Send a criterion that failed review back to |
| Resolve a review ( |
| Block a criterion with a category and reason |
| Ask the project owner a question when the spec is unclear (blocks the criterion until answered) |
| Collect the answers to your questions |
| Unblock a criterion with a resolution |
| Propose a spec change for the owner to review when the code must differ; never edits the spec |
| Kanban transition history (for incremental sync) |
| ⚠️ Deprecated — use the lifecycle tools above |
Version control
Tool | Description |
| List changesets (your writes + history) with op counts; |
| What changed in the spec since a sequence number, and which criteria that affects |
| A release's work grouped as new, modified and removed (with the code paths to delete) |
| A release's raw diff against its baseline |
| Report changed paths since the last sync so VibeMap can flag spec drift |
Codebase
Tool | Description |
| Walk a local directory |
| Reverse-engineer a codebase into VibeMap assets |
| Submit a structural code map (nodes/edges) rendered on the project's Codebase tab |
| Fetch the project's current code map (status, nodes/edges, sync anchor + drift) |
| Poll AI generation task status |
Import an existing codebase
The structure is read on your machine with no model and no network call. What reaches VibeMap is the structural facts (table, column, policy and route definitions with their file paths) and the spec text your agent writes. File contents never leave your machine.
Tool | Description |
| Read the repository's tables, policies, routes and file clusters locally; sends nothing |
| Send the facts: VibeMap creates the schema, access rules and a page per route, each linked to its file |
| Send the features, stories and criteria your agent wrote, each citing its source files |
| Pass the imported criteria (unverified), lock MVP1 and open MVP2 |
| Apply the structural changes at your current commit and flag the specs the changed files touch |
| Clear handled files, map units or criteria from the drift report |
| Apply or dismiss one staged code-drift proposal |
Prompts (slash commands)
The server also exposes prompts — invocable workflows your IDE surfaces as slash commands (in Claude Code: /mcp__vibemap__<name>). The body of each prompt is expanded from VibeMap's server at call time, so you invoke a workflow rather than paste a long instruction. Every prompt takes a projectId except new_project, which is the one that creates a project; the code-oriented ones also accept an optional localPath.
Prompt | Args | Description |
| — | Guided interview that creates a new VibeMap project. Start here |
|
| Author the full spec graph from your local codebase (bring-your-own-agent, code-first) |
|
| Author the full spec graph from the project idea (bring-your-own-agent, idea-first) |
|
| Stage 1 of 5 — author just the personas |
|
| Stage 2 of 5 — author just the features |
|
| Stage 3 of 5 — author just the user stories |
|
| Stage 4 of 5 — author just the acceptance criteria |
|
| Stage 5 of 5 — author just the pages |
|
| Author the database schema — tables, columns, relationships |
|
| Detect and reconcile spec drift since the last sync |
|
| Build and submit a structural code map |
|
| Load the project's spec context into your agent |
|
| Show the project's kanban board |
|
| Import an existing codebase as a locked MVP1: extract locally, import the facts, write the spec per cluster, finalize |
|
| Bring an imported project up to date and stage drift proposals for review |
|
| Build the ready work test first while the board follows live; CI verifies, the agent never marks anything done |
|
| Build the next release: new and modified items, and delete what was removed |
gen_* — run VibeMap's own generators
The author_* prompts above run on your model: your agent does the thinking and VibeMap just stores the result. The gen_* prompts are the other half — they run VibeMap's hosted generation pipelines, the same ones behind the app's /gen-… slash commands. They are metered (they draw down the project owner's VibeMap token budget) and asynchronous (you get a sessionId back and poll vibemap_get_generation_status).
Prompt | Args | Description |
|
| Generate personas — who you're building for |
|
| Generate features — the set every story, page and table hangs off |
|
| Generate user stories from your features |
|
| Derive acceptance criteria from features and stories |
|
| Generate the page architecture from features and stories |
|
| Generate the database schema — tables and relationships |
|
| Cross-check acceptance criteria against your page layouts |
Reporting test results from CI
ci-report turns a test run into review results. Tag each test name with the acceptance criterion it proves, for example [AC-042] rejects an empty title. After the run, post the report:
VIBEMAP_CI_TOKEN=... npx @vibemap.ai/mcp-server ci-report \
--junit junit.xml --project <project-id>Every criterion that is in review and mentioned by the report is resolved from its own tests: passed when all of them passed, failed when any failed (the failing test names go back to the agent). Criteria that are not in review, or are unknown, are listed and left alone.
Formats:
--junit(JUnit XML),--vitestand--playwright(each tool's JSON reporter). Pass several to combine them.VIBEMAP_CI_TOKENmust be a CI-review token (Account, Developer, scope "CI review"). An agent token is refused.The run URL and commit are picked up automatically on GitHub Actions; otherwise pass
--run-urland--sha.Exit codes:
0reported,1the server rejected the report or could not be reached,2bad usage,3no tagged tests with--strict.--dry-runprints the request without sending it.
Documentation
Full docs at vibemap.ai/docs/developer-docs/mcp-server/introduction
License
MIT
Available Tools
32 toolsvibemap_analyze_codebaseA
Scan a local codebase and submit it to VibeMap for AI-powered reverse engineering. The server-side generation persists FEATURES from the code digest. It does NOT persist user stories or acceptance criteria — after the features task completes (poll vibemap_get_generation_status), create those yourself with vibemap_create_user_story and vibemap_create_acceptance_criterion, using your full codebase access for accuracy. Returns a sessionId to poll.
Inputs: localPath (required), projectId (required), depth, taskTitle.
vibemap_block_criterionA
Mark a criterion as blocked. Transitions any-active-status → blocked. Use this when external dependency, ambiguity, or environmental issue prevents progress.
Inputs: reason (required), category (required), criterionId (required).
vibemap_claim_criterionA
Atomically claim an acceptance criterion for implementation. Transitions ready → in_progress. Returns 409 (race) if another agent already claimed it.
Inputs: criterionId (required).
vibemap_create_acceptance_criterionA
Create a new acceptance criterion for a user story in BDD format (Given/When/Then). Use this to flesh out what 'done' means for a story before or during implementation. You can call this multiple times to add multiple scenarios (happy path, error cases, edge cases) to the same story.
Inputs: storyId (required), whenAction (required), thenOutcome (required), givenCondition (required), +3 more.
vibemap_create_featureA
Create a new feature in a VibeMap project. Use this when reverse-engineering a codebase to register discovered capabilities.
Inputs: name (required), projectId (required), effort, category, +4 more.
vibemap_create_projectA
Create a new VibeMap project. Use this when starting from an existing codebase — create the project first, then call vibemap_analyze_codebase with the returned project ID.
Inputs: name (required), description (required).
vibemap_create_user_storyC
Create a new user story inside a VibeMap feature. Provide the user role, action, and expected outcome.
Inputs: title (required), featureId (required), description (required), soThat, +4 more.
vibemap_get_atomic_blueprintARead-only
Retrieve a code-shaped atomic blueprint of a VibeMap project — relationships hydrated, Kanban metadata stripped, with synthesized interactions and entity state machines. Designed for LLM coders building the application end-to-end. Prefer this over vibemap_get_project_context when generating code; the blueprint omits PM narrative and process metadata to maximise signal-per-token.
Inputs: projectId (required).
vibemap_get_code_mapARead-only
Fetch the project's current code map (status draft|confirmed, nodes/edges, sync anchor incl. any drift report). Use before re-submitting to preserve the user's hidden-node curation where possible.
Inputs: projectId (required).
vibemap_get_generation_statusARead-only
Poll the status of a VibeMap AI generation task (e.g., reverse engineering or spec generation). Use the sessionId returned by vibemap_analyze_codebase.
Inputs: sessionId (required).
vibemap_get_kanban_boardARead-only
Get a real-time kanban board view of a project grouped by status columns. Shows features with their stories nested underneath. Ideal for an IDE agent to understand what's planned, in progress, and done.
Inputs: projectId (required), includeCriteria.
vibemap_get_next_ready_criterionARead-only
Get the highest-priority acceptance criterion in ready status for the given project. Returns the criterion to work on next, or null if nothing is ready.
Inputs: projectId (required).
vibemap_get_page_sourceARead-only
Retrieve a VibeMap page's generated source code so you can pull it straight into a repo. Returns the page's own source_code plus the source_code of each of its sections. Use this to export a generated page into your codebase instead of copy-pasting.
Inputs: pageId (required), projectId (required).
vibemap_get_project_contextARead-only
Retrieve the full context of a VibeMap project including features, user stories, personas, pages, and database schema. Use this before building a feature to understand all the specs.
Inputs: projectId (required), includePages, includeSchema, includeStories, +2 more.
vibemap_list_acceptance_criteriaBRead-only
List acceptance criteria for a story, feature, or project. Returns BDD-formatted criteria (Given/When/Then) with status.
Inputs: limit, offset, status, storyId, +2 more.
vibemap_list_access_rulesARead-only
List a VibeMap project's access-control rules: table-level rules (per persona/role, with can_select/insert/update/delete and structured op_conditions predicates like "own rows only") and page-level rules (can_view/create_content/edit/delete with predicates), plus an advisory reconciliation summary flagging page↔table drift. Use this to generate correct RLS policies and route/UI authorization — the atomic blueprint only carries page-level conditions, so call this for table-level (RLS) access control.
Inputs: projectId (required).
vibemap_list_changesetsARead-only
List a VibeMap project's version-control changesets (most recent first) with a per-changeset op count. Every write you make through this server is wrapped in a changeset, so use this to see the changesets your own edits produced, audit who/what changed the project, or review recent edit history. Pass includeOps=true to inline each changeset's individual operations (entity_type, op, diff).
Inputs: projectId (required), limit, includeOps.
vibemap_list_featuresARead-only
List features for a VibeMap project. Supports filtering by status, priority, category, and search. Returns paginated results.
Inputs: projectId (required), limit, offset, search, +3 more.
vibemap_list_kanban_eventsARead-only
List kanban transition events for a project, newest first. Use since to fetch only events after a timestamp (for reconnect-backfill).
Inputs: projectId (required), limit, since.
vibemap_list_projectsARead-only
List all VibeMap projects for the authenticated user. Returns project IDs, names, descriptions, and status.
Inputs: no named parameters.
vibemap_list_user_storiesARead-only
List user stories for a project or feature. Filter by status, priority. Returns paginated results with full story detail.
Inputs: limit, offset, search, status, +3 more.
vibemap_report_progressA
Append a progress event to the criterion timeline without changing its status. Used to surface intermediate work for visibility.
Inputs: summary (required), criterionId (required).
vibemap_resolve_reviewA
Resolve a criterion in review. Transitions in_review → passed | failed. NOTE: agents (env_token:agent) cannot self-resolve their own work — this tool requires a CI-scoped token (env_token:ci) or a session user.
Inputs: outcome (required), criterionId (required), notes, testRunUrl.
vibemap_scan_codebaseARead-only
Scan a local directory and return a formatted tree view plus file statistics. Use this to explore and understand an existing codebase before syncing to VibeMap.
Inputs: localPath (required), depth.
vibemap_submit_code_mapA
Submit a structural code map of the user's codebase to VibeMap (rendered on the project's Codebase tab). Build it yourself from your codebase access: one node per meaningful unit (page/route, API endpoint, data model, service, module, config), edges for imports/routes/reads/writes. Node kinds: page|api|model|service|module|config. Layers: ui|api|data|services|shared. Edge kinds: imports|routes|reads|writes. Use repo-relative paths as node ids. Max 500 nodes — aggregate small files into their module. Re-submitting replaces the project's map and resets it to draft for the user to re-confirm.
Inputs: map (required), projectId (required), anchor.
vibemap_submit_for_reviewA
Submit completed work for review. Transitions in_progress → in_review. Requires a git SHA and a diff URL as evidence.
Inputs: gitSha (required), diffUrl (required), criterionId (required), notes.
vibemap_sync_changesA
Report codebase changes since the last sync so VibeMap can flag spec drift. Workflow: 1) call vibemap_get_code_map and read anchor.commitSha; 2) run git diff --name-only <commitSha>..HEAD (plus untracked files from git status --porcelain); 3) call this tool with the changed paths and your current HEAD sha. The response lists affected map units and features — update the stale specs with vibemap_update_feature / vibemap_update_user_story / vibemap_update_acceptance_criterion (all changeset-audited), then re-submit the code map with vibemap_submit_code_map to clear the drift.
Inputs: projectId (required), changedFiles (required), headSha.
vibemap_unblock_criterionB
Unblock a criterion. Transitions blocked → prior_status (recorded when block was set; defaults to ready).
Inputs: resolution (required), criterionId (required).
vibemap_update_acceptance_criterionBIdempotent
Update an acceptance criterion's status or content. Use status 'passed' when your code satisfies the criterion, 'failed' when it does not.
Inputs: criterionId (required), status, whenAction, description, +3 more.
vibemap_update_featureBIdempotent
Update an existing feature's fields or status in VibeMap.
Inputs: featureId (required), name, effort, status, +5 more.
vibemap_update_kanban_statusAIdempotent
[DEPRECATED — use the typed transition tools (claim, report_progress, submit_for_review, resolve_review, block, unblock) instead. This tool will be removed in a future release.] Atomically advance or update the kanban status of a feature, user story, or acceptance criterion. Validates allowed state transitions and prevents invalid moves. Call this when you start or finish implementing something.
Feature stages: draft → open → in_progress → completed Story stages: draft → has_criteria → open → in_progress → completed Criterion stages: draft → pending → passed | failed
Inputs: entityId (required), newStatus (required), entityType (required), notes.
vibemap_update_user_storyCIdempotent
Update an existing user story's fields or status in VibeMap.
Inputs: storyId (required), title, soThat, status, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools have clearly distinct purposes, organized by resource type and action. However, the deprecated 'vibemap_update_kanban_status' overlaps with the newer transition tools, and 'vibemap_get_project_context' vs 'vibemap_get_atomic_blueprint' could be confused without careful reading.
All tools follow a consistent 'vibemap_verb_noun' pattern (e.g., list_projects, create_feature, get_atomic_blueprint). No mixing of conventions or unpredictable names.
32 tools is higher than the typical 3-15, but each tool serves a distinct purpose in the comprehensive project management and reverse engineering workflow. The count is justified, though it may feel heavy for simpler use cases.
The tool set covers CRUD for core entities (features, stories, criteria), kanban workflow, code analysis, and drift detection. However, missing deletion tools for projects, features, and stories, which is a minor gap.
Maintenance
Related MCP Connectors
Connect existing AI agents via OAuth or MCP; join a public lobby, find work and coordinate projects.
Connect AI agents to Filepad workspaces through OAuth MCP.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
StremAI MCP: shared memory for AI coding agents. Connected agents can recall. OAuth + local stdio.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects ChatGPT to a local developer workspace through MCP, enabling bounded repository analysis, file and image inspection, direct edits, command verification, and Git-aware review.22MIT
- AlicenseNot gradedqualityBmaintenanceConnects MCP-compatible AI clients and agents to one durable Project Brain plus controlled access to authorized project folders on your own machine. Enables file editing, terminal and Git operations, project intelligence, browser automation, and local MCP server federation, all scoped to explicit workspace grants.55 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceConnects ChatGPT and MCP clients to authorized local development environments, enabling secure file access, shell execution, persistent tasks, browser/desktop control, and remote management of projects.19MIT
- AlicenseNot gradedqualityBmaintenanceConnects ChatGPT Web to a local development environment, enabling file reads and patches, shell execution, plan updates, and isolated worktree coordination through permissioned MCP tools.13MIT