@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.

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 chat input.

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
`VIBEMAP_API_KEY`	Your Personal Access Token (`vm_...`)	Required
`VIBEMAP_BASE_URL`	VibeMap instance URL	`http://localhost:3000`

Tools

The server exposes 36 tools via the vibemap_ prefix.

Projects & context

Tool	Description
`vibemap_list_projects`	List all your projects
`vibemap_create_project`	Create a new project (use before `analyze_codebase`)
`vibemap_get_project_context`	Load full project specs into agent context
`vibemap_get_atomic_blueprint`	Get the code-shaped atomic blueprint for LLM generation
`vibemap_list_access_rules`	List table- and page-level access rules (with `op_conditions`) for RLS + auth
`vibemap_get_page_source`	Retrieve a page and its section source code

Personas & pages (spec authoring)

Tool	Description
`vibemap_create_persona`	Create a rich user persona (demographics, goals, pain points, …)
`vibemap_create_page`	Create a page/screen in the project's page inventory
`vibemap_create_schema`	Persist the database schema (tables → columns → relationships) in one call

Conversational agent (Engine B — hosted, metered)

Tool	Description
`vibemap_agent`	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 + `operationId` to approve in a second call; long generations run in the background (poll `get_generation_status`)

Features

Tool	Description
`vibemap_list_features`	List features with filtering
`vibemap_create_feature`	Create a new feature
`vibemap_update_feature`	Update feature fields or status (validates transitions)

User stories

Tool	Description
`vibemap_list_user_stories`	List stories by project or feature
`vibemap_create_user_story`	Create a user story
`vibemap_update_user_story`	Update story fields or status (validates transitions)

Acceptance criteria

Tool	Description
`vibemap_list_acceptance_criteria`	Fetch BDD criteria
`vibemap_create_acceptance_criterion`	Create a BDD acceptance criterion
`vibemap_update_acceptance_criterion`	Update or mark criteria passed/failed (validates transitions)

Kanban — board & agentic lifecycle

Tool	Description
`vibemap_get_kanban_board`	Get a real-time board view
`vibemap_get_next_ready_criterion`	Get the highest-priority criterion ready to work on
`vibemap_claim_criterion`	Claim a criterion (`ready` → `in_progress`)
`vibemap_report_progress`	Append a progress event to a criterion
`vibemap_submit_for_review`	Submit a criterion for review (→ `review_pending`)
`vibemap_resolve_review`	Resolve a review (`passed` / `failed`)
`vibemap_block_criterion`	Block a criterion with a category and reason
`vibemap_unblock_criterion`	Unblock a criterion with a resolution
`vibemap_list_kanban_events`	Kanban transition history (for incremental sync)
`vibemap_update_kanban_status`	⚠️ Deprecated — use the lifecycle tools above

Version control

Tool	Description
`vibemap_list_changesets`	List changesets (your writes + history) with op counts; `includeOps` for diffs
`vibemap_sync_changes`	Report changed paths since the last sync so VibeMap can flag spec drift

Codebase

Tool	Description
`vibemap_scan_codebase`	Walk a local directory
`vibemap_analyze_codebase`	Reverse-engineer a codebase into VibeMap assets
`vibemap_submit_code_map`	Submit a structural code map (nodes/edges) rendered on the project's Codebase tab
`vibemap_get_code_map`	Fetch the project's current code map (status, nodes/edges, sync anchor + drift)
`vibemap_get_generation_status`	Poll AI generation task status

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
`new_project`	—	Guided interview that creates a new VibeMap project. Start here
`author_spec`	`projectId`, `localPath?`	Author the full spec graph from your local codebase (bring-your-own-agent, code-first)
`author_idea`	`projectId`	Author the full spec graph from the project idea (bring-your-own-agent, idea-first)
`author_personas`	`projectId`	Stage 1 of 5 — author just the personas
`author_features`	`projectId`	Stage 2 of 5 — author just the features
`author_stories`	`projectId`	Stage 3 of 5 — author just the user stories
`author_criteria`	`projectId`	Stage 4 of 5 — author just the acceptance criteria
`author_pages`	`projectId`	Stage 5 of 5 — author just the pages
`author_schema`	`projectId`, `localPath?`	Author the database schema — tables, columns, relationships
`sync_changes`	`projectId`, `localPath?`	Detect and reconcile spec drift since the last sync
`code_map`	`projectId`, `localPath?`	Build and submit a structural code map
`load_context`	`projectId`	Load the project's spec context into your agent
`kanban`	`projectId`	Show the project's kanban board

`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
`gen_personas`	`projectId`	Generate personas — who you're building for
`gen_features`	`projectId`	Generate features — the set every story, page and table hangs off
`gen_stories`	`projectId`	Generate user stories from your features
`gen_criteria`	`projectId`	Derive acceptance criteria from features and stories
`gen_pages`	`projectId`	Generate the page architecture from features and stories
`gen_schema`	`projectId`	Generate the database schema — tables and relationships
`gen_sync_criteria_from_pages`	`projectId`	Cross-check acceptance criteria against your page layouts

Documentation

Full docs at vibemap.ai/docs/developer-docs/mcp-server/introduction

License

MIT

vibemap mcp